# LangChainAPI

**Repository Path**: psychology_agent/langchain-api

## Basic Information

- **Project Name**: LangChainAPI
- **Description**: LangChain智能体+FastApi接口
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Psychology Agent - 青少年心理健康智能体

## Agent 介绍

`psychology_agent` 是一个基于 FastAPI 和 LangChain 构建的 AI 心理咨询智能体服务。它是一位温暖、专业的"虚拟心理咨询师"，名叫"心晴伙伴"，专门为青少年提供心理健康支持。

### 它能做什么

- **倾听与陪伴**: 像朋友一样倾听青少年的心声，不加评判，只有理解和支持
- **专业心理知识**: 基于心理学知识库，提供科学、实用的心理调适方法
- **个性化建议**: 根据用户的档案、历史对话和测评结果，提供个性化建议
- **危机干预**: 自动识别危机信号（如自伤、自杀念头），提供援助资源
- **长期记忆**: 记住用户的历史对话和关键信息，建立连续的咨询关系
- **多维度数据整合**: 整合用户的睡眠、压力、情绪游戏等数据，全面了解用户状态

### 核心价值

| 价值 | 说明 |
|------|------|
| **专业可信** | 基于心理学专业知识库，回答有依据、可落地 |
| **温暖陪伴** | 语言风格温暖亲切，适合青少年群体 |
| **安全守护** | 危机信号自动识别，及时提供援助资源 |
| **个性化** | 基于用户档案和历史数据，提供针对性建议 |
| **持续学习** | 通过长期记忆和摘要，建立连续咨询关系 |

---

## 核心机制

### LangChain Agent 工作原理

本智能体基于 LangChain Agent 框架构建，核心流程如下：

```
用户消息 → Agent 分析 → 工具调用 → 知识检索 → 生成响应 → SSE 流式输出
```

1. **消息接收**: 通过 SSE 流式接口接收用户消息
2. **上下文加载**: 从 Redis 加载历史对话摘要和最近消息
3. **意图识别**: Agent 分析用户意图，决定是否需要调用工具
4. **工具调用**: 根据需要调用心理知识检索、用户档案查询等工具
5. **响应生成**: LLM 基于上下文和工具返回生成回复
6. **流式输出**: 通过 SSE 逐字输出，实现打字机效果
7. **记忆更新**: 将新对话写入 Redis，必要时触发摘要生成

### 对话记忆机制

#### 记忆架构

```
┌─────────────────────────────────────┐
│         Redis 记忆存储               │
├─────────────────────────────────────┤
│  工作记忆 (Working Memory)          │
│  - 最近 16 条对话原文（约 8 轮对话）  │
│  - TTL: 1 小时                        │
├─────────────────────────────────────┤
│  长期摘要 (Summary)                 │
│  - 早期对话压缩摘要                  │
│  - 关键话题提炼                      │
│  - TTL: 3 天                          │
├─────────────────────────────────────┤
│  总结锁 (Summarizing Lock)          │
│  - 防止同一对话并发触发多次总结       │
│  - TTL: 5 分钟                        │
└─────────────────────────────────────┘
```

#### 记忆管理流程

1. **添加消息**: 每轮对话添加到 Redis List（键：`agent:memory:working:{conversation_id}`）
2. **阈值检测**: 当工作记忆达到 16 条（约 8 轮对话）时触发异步总结
3. **异步心理评估**: 后台线程执行心理评估，分析用户情绪状态和风险等级
4. **异步对话总结**: 使用轻量级模型（qwen2.5）对早期对话进行压缩总结
5. **摘要更新**: 将心理评估结果和对话摘要写入 Redis（键：`agent:memory:summary:{conversation_id}`）
6. **记忆清理**: 清空工作记忆，保留摘要供后续对话使用
7. **并发控制**: 使用 Redis 锁（键：`agent:memory:summarizing:{conversation_id}`）防止同一对话并发触发多次总结

#### 摘要生成策略

- **总结模型**: 使用轻量级模型（qwen2.5）进行快速总结
- **摘要内容**: 包含对话主题、关键发现、用户状态等
- **并发控制**: 使用 Redis 锁防止同一对话并发触发多次总结

### RAG 知识检索机制

#### 知识检索流程

```
用户问题 → 生成查询 → Embedding 向量化 → Chroma 相似度搜索 → 返回 Top-K 相关文档
```

1. **查询构建**: 根据用户问题构建检索查询
2. **向量化**: 使用 Embedding 模型将查询转换为向量
3. **相似度搜索**: 在 Chroma 向量库中搜索相似文档
4. **结果过滤**: 根据相似度阈值过滤不相关文档
5. **上下文整合**: 将检索结果作为上下文提供给 LLM

#### 知识库分类

知识库文档按以下类别组织：

| 分类 | 说明 |
|------|------|
| `counseling_techniques` | 心理咨询技术、沟通技巧 |
| `adolescent_psychology` | 青少年心理发展特征 |
| `crisis_intervention` | 危机干预流程、资源 |
| `assessments` | 心理测评量表解读 |

---

## 工具 (Tools) 列表

智能体配备了以下工具，可根据需要调用：

### 1. 危机干预工具

#### assess_crisis_level
- **功能**: 评估用户消息的危机等级
- **触发场景**: 用户表达自伤、自杀、绝望等念头
- **参数**: `message` (用户消息内容)
- **返回**: 危机等级 (normal/medium/high)、关键词、干预建议、援助热线

#### get_crisis_resources
- **功能**: 获取危机干预资源
- **触发场景**: 危机评估后，提供具体援助信息
- **参数**: 无
- **返回**: 心理援助热线列表和紧急情况处理指南

### 2. 用户信息工具

#### get_user_profile
- **功能**: 获取用户档案信息
- **触发场景**: 需要了解用户基本情况时
- **参数**: `user_id`, `token`
- **返回**: 用户基本信息（昵称、年龄、年级、压力水平、睡眠质量等）

#### get_user_consultation_history
- **功能**: 获取用户历史咨询记录
- **触发场景**: 需要参考用户历史对话时
- **参数**: `user_id`, `token`
- **返回**: 历史测评/咨询记录列表

#### get_user_assessments
- **功能**: 获取用户心理测评记录
- **触发场景**: 用户提到测评或需要分析心理状态波动
- **参数**: `user_id`, `token`
- **返回**: SAS、SDS、SCL90 等测评结果

#### get_emotion_game_history
- **功能**: 获取用户情绪游戏历史记录
- **触发场景**: 用户提到情绪游戏或表情识别
- **参数**: `token`
- **返回**: 情绪游戏历史记录列表

#### get_weekly_data
- **功能**: 获取用户一周睡眠和压力数据
- **触发场景**: 用户提到睡眠、压力、休息情况
- **参数**: `token`
- **返回**: 周睡眠数据（平均时长、质量评分）和周压力数据（压力等级、来源）

### 3. 测评解读工具

#### interpret_assessment_score
- **功能**: 解释测评量表分数
- **触发场景**: 需要解读具体测评分数
- **参数**: `test_type` (SAS/SDS/SCL90), `score` (分数)
- **返回**: 分数解释和建议（如"标准分 55 分，存在轻度焦虑"）

### 4. 知识检索工具

#### search_psychology_knowledge
- **功能**: 从心理学知识库检索相关信息
- **触发场景**: 用户询问心理学知识、心理问题应对方法
- **参数**: `query` (查询关键词)
- **返回**: 相关心理学知识片段（包含分类、来源、相似度）

#### get_psychology_context
- **功能**: 获取特定主题的心理学背景知识
- **触发场景**: 需要深入了解某个心理学主题
- **参数**: `topic` (如"焦虑"、"抑郁"、"学习压力"、"人际关系")
- **返回**: 按类别整理的主题知识

---

## 项目结构

```
psychology_agent/
├── app/
│   ├── __init__.py              # 包初始化
│   ├── main.py                  # FastAPI 应用入口
│   ├── config.py                # 配置管理
│   │
│   ├── api/                     # API 接口层
│   │   ├── __init__.py
│   │   ├── routes.py            # 路由定义（/api/chat/stream）
│   │   └── schemas.py           # 请求/响应模型
│   │
│   ├── agents/                  # Agent 层
│   │   ├── __init__.py
│   │   ├── psychologist.py      # 心理咨询师 Agent 创建
│   │   └── prompts.py           # 系统提示词模板
│   │
│   ├── tools/                   # 工具层
│   │   ├── __init__.py
│   │   ├── crisis.py            # 危机干预工具
│   │   ├── profile.py           # 用户档案工具
│   │   ├── assessment.py        # 心理测评工具
│   │   ├── weekly_data.py       # 周数据工具
│   │   ├── emotion_game.py      # 情绪游戏工具
│   │   └── rag_tool.py          # RAG 知识检索工具
│   │
│   ├── memory/                  # 记忆管理层
│   │   ├── __init__.py
│   │   ├── redis_memory.py      # Redis 记忆存储
│   │   ├── conversation.py      # 对话记忆管理
│   │   ├── summarizer.py        # 记忆摘要生成
│   │   └── assessment.py        # 心理评测与总结
│   │
│   ├── rag/                     # RAG 检索层
│   │   ├── __init__.py
│   │   ├── retriever.py         # RAG 检索器
│   │   ├── vectorstore.py       # Chroma 向量存储
│   │   └── embeddings.py        # Embedding 服务
│   │
│   ├── llm/                     # LLM 层
│   │   ├── __init__.py
│   │   └── provider.py          # LLM 模型提供
│   │
│   └── ingest/                  # 数据导入层
│       ├── __init__.py
│       └── knowledge.py         # 知识库导入脚本
│
├── data/
│   ├── knowledge/               # 心理学知识库文档
│   │   ├── counseling_techniques/
│   │   ├── adolescent_psychology/
│   │   ├── crisis_intervention/
│   │   └── assessments/
│   └── chroma/                  # Chroma 向量库数据
│
├── .env                         # 环境变量配置
├── .env.example                 # 环境变量示例
├── requirements.txt             # Python 依赖
├── docker-compose.yml           # Docker 编排
├── start.bat                    # Windows 启动脚本
└── test_*.py                    # 测试脚本
```

---

## 向量数据库 (Chroma) 集成

### 知识库准备

1. **知识库文档**: 将心理学知识整理为 Markdown 文档，按类别存放在 `data/knowledge` 目录

2. **文档格式示例**:

```markdown
# 青少年焦虑的应对策略

## 焦虑的表现

青少年焦虑可能表现为...

## 应对方法

1. 深呼吸练习
2. 渐进式肌肉放松
3. 正念冥想
...
```

### 知识库导入

运行以下脚本将知识文档导入向量库：

```bash
# 进入项目目录
cd psychology_agent

# 运行导入脚本
python -m app.ingest.knowledge
```

导入过程：
1. 扫描 `data/knowledge` 目录下所有 Markdown 文件
2. 按类别（counseling_techniques、adolescent_psychology 等）处理
3. 将长文档分割为适合向量化的片段（约 1000 字符）
4. 使用 Embedding 模型生成向量
5. 存储到 Chroma 向量库，附带元数据（分类、来源等）

### AI 检索流程

当用户询问心理学问题时：

1. **查询向量化**: 使用 Embedding 模型将用户问题转换为向量
2. **相似度搜索**: 在 Chroma 中搜索最相似的文档片段（默认返回 Top 3）
3. **结果过滤**: 过滤相似度低于阈值的文档
4. **上下文整合**: 将检索结果作为上下文提供给 LLM
5. **响应生成**: LLM 基于检索到的专业知识生成回答

---

## 初始化与启动

### 环境要求

| 软件 | 版本 | 说明 |
|------|------|------|
| Python | 3.10+ | 运行环境 |
| pip | 21.0+ | 包管理工具 |
| Ollama | latest | 本地 LLM 运行平台 |
| Redis | 6.0+ | 记忆存储 |
| Git | - | 代码管理（可选） |

### 安装依赖

#### 1. 创建虚拟环境（推荐）

```bash
# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate
```

#### 2. 安装 Python 依赖

```bash
pip install -r requirements.txt
```

主要依赖（如 requirements.txt 不完整，请手动安装以下包）：
- `fastapi`: Web 框架
- `uvicorn`: ASGI 服务器
- `langchain-core`: LangChain 核心框架
- `langchain-ollama`: Ollama LLM 集成（如使用本地 Ollama）
- `openai`: OpenAI 兼容 API 客户端（如使用阿里云通义千问）
- `chromadb`: 向量数据库
- `redis`: Redis 客户端
- `httpx`: HTTP 客户端
- `pydantic`: 数据验证
- `python-dotenv`: 环境变量管理
- `numpy`: 数值计算
- `aiofiles`: 异步文件操作

可以使用以下命令安装完整依赖：

```bash
pip install fastapi uvicorn langchain-core langchain-ollama openai chromadb redis httpx pydantic python-dotenv numpy aiofiles
```

### 配置环境变量

项目支持两种 LLM 配置方式：**本地 Ollama 模型**（默认）和**阿里云通义千问 API**。默认配置使用本地 Ollama，如需使用阿里云通义千问，请按以下说明配置。

复制环境变量模板：

```bash
cp .env.example .env
```

#### 配置方式一：本地 Ollama 模型（默认）

编辑 `.env` 文件，配置以下关键变量：

```ini
# LLM 配置 - 使用本地 Ollama
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
LLM_MODEL=qwen3.5:9b
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=2000
SUMMARIZE_MODEL=qwen2.5  # 用于记忆总结的轻量级模型
SUMMARIZE_MAX_TOKENS=1200

# Embedding 配置 - 使用本地 Ollama Embedding 模型
EMBEDDING_MODEL=qwen3-embedding:4b
EMBEDDING_DIMENSION=1024

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=

# Chroma 向量库配置
CHROMA_PERSIST_DIR=./data/chroma
CHROMA_COLLECTION=psychology_memory
VECTOR_TOP_K=3  # 检索返回的文档数量

# Spring Boot 后端配置
SPRINGBOOT_BASE_URL=http://localhost:8080
SERVICE_TO_SERVICE_TOKEN=Bearer your-service-to-service-token-here  # 服务间通信 Token

# 服务配置
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
```

#### 配置方式二：阿里云通义千问 API

如需使用阿里云通义千问 API，请使用 `.env.example` 中的默认配置，并设置您的 API 密钥：

```ini
# LLM 配置 - 使用阿里云通义千问
LLM_PROVIDER=openai
OPENAI_API_KEY=your-api-key-here
OPENAI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL=qwen-plus
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=2000

# Embedding 配置
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSION=1536

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=

# Redis 向量索引配置
VECTOR_INDEX_NAME=psychology_knowledge
VECTOR_DIMENSION=1536
VECTOR_TOP_K=3

# Spring Boot 后端配置
SPRINGBOOT_BASE_URL=http://localhost:8080
SERVICE_TO_SERVICE_TOKEN=Bearer your-service-to-service-token-here

# 服务配置
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
```

### 启动 Ollama 模型

确保 Ollama 服务已启动，并拉取所需模型：

```bash
# 启动 Ollama（如未运行）
ollama serve

# 拉取模型
ollama pull qwen3.5:9b
ollama pull qwen3-embedding:4b
ollama pull qwen2.5
```

### 启动服务

#### 方式 1：使用启动脚本（Windows）

```bash
# 直接运行启动脚本
start.bat
```

#### 方式 2：使用 Uvicorn 命令

```bash
# 开发模式（支持热重载）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

#### 方式 3：使用 Python 直接运行

```bash
python -m app.main
```

### 验证启动

访问健康检查接口：

```bash
curl http://localhost:8000/health
```

看到以下响应表示启动成功：

```json
{"status":"healthy"}
```

### 测试对话

使用以下命令测试流式对话：

```bash
# 使用测试脚本
python test_chat_stream.py

# 或使用 curl 测试
curl -X POST http://localhost:8000/api/chat/stream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{"message":"你好","sessionId":"test-session","conversationId":1}'
```

---

## 常见问题

### 1. Ollama 连接失败

**问题**: 启动时报 Ollama 连接错误

**解决**:
- 确认 Ollama 服务已启动：`ollama serve`
- 检查 `OLLAMA_BASE_URL` 配置是否正确
- 确认模型已拉取：`ollama list`

### 2. Redis 连接失败

**问题**: 对话功能异常，提示 Redis 不可用

**解决**:
- 确认 Redis 服务已启动：`redis-server` 或 `docker run redis`
- 检查 `REDIS_HOST` 和 `REDIS_PORT` 配置
- 测试 Redis 连接：`redis-cli ping`

### 3. Chroma 向量库为空

**问题**: RAG 检索返回空结果

**解决**:
- 运行知识库导入脚本：`python -m app.ingest.knowledge`
- 确认 `data/knowledge` 目录存在且有文档
- 检查 Chroma 持久化目录配置

---

## 许可证

本项目为青少年心理健康研究专用，请勿用于商业用途。