# LangChain 对话机器人实施指南

## 项目概述
本指南将帮助您基于现有的 requirements.txt 和 .env 配置，快速搭建一个集成 LangChain 和 LangGraph 的智能对话机器人项目。

## 项目结构
```
langchain-project/
├── .env                          # 环境变量配置
├── requirements.txt              # Python 依赖
├── src/                          # 源代码目录
│   ├── __init__.py
│   ├── main.py                   # FastAPI 应用入口
│   ├── cli_chat.py              # 命令行对话程序
│   ├── models/                   # 数据模型
│   │   ├── __init__.py
│   │   └── chat_models.py
│   ├── services/                 # 业务服务
│   │   ├── __init__.py
│   │   ├── ollama_service.py     # Ollama 模型服务
│   │   └── langsmith_service.py  # LangSmith 监控服务
│   ├── workflows/                # LangGraph 工作流
│   │   ├── __init__.py
│   │   ├── chat_workflow.py      # 主要对话工作流
│   │   └── nodes/                # 工作流节点
│   │       ├── __init__.py
│   │       ├── intent_analysis.py
│   │       ├── order_diagnosis.py
│   │       └── natural_chat.py
│   ├── chains/                   # LangChain 链
│   │   ├── __init__.py
│   │   └── simple_chat_chain.py
│   └── utils/                    # 工具函数
│       ├── __init__.py
│       ├── config.py             # 配置管理
│       └── logger.py             # 日志配置
├── data/                         # 数据目录
│   └── mock_orders.json         # 模拟订单数据
└── tests/                        # 测试目录
    ├── __init__.py
    └── test_workflows.py
```

## 核心实现要点

### 1. 环境配置
您的 .env 文件已经配置完善，包含：
- Ollama 模型配置（路由模型：qwen3:8b，对话模型：deepseek-v3.1:671b-cloud）
- LangSmith 监控配置
- FastAPI 服务配置

### 2. 简单 Chain 实现 (cli_chat.py)
```python
# 关键实现点：
# 1. 使用 LangChain 的 ChatOllama 连接本地模型
# 2. 创建简单的对话链
# 3. 命令行循环交互
# 4. 集成 LangSmith 监控
```

### 3. LangGraph 工作流实现 (chat_workflow.py)
```python
# 关键实现点：
# 1. 定义状态图节点：意图分析 -> 分支处理 -> 输出
# 2. 实现流式输出机制
# 3. 状态管理和上下文传递
# 4. 错误处理和重试机制
```

### 4. 意图分析节点 (intent_analysis.py)
```python
# 关键实现点：
# 1. 使用 qwen3:8b 模型进行意图分类
# 2. 结构化输出（订单诊断 vs 自然对话）
# 3. 置信度评估
# 4. 意图分析结果的状态传递
```

### 5. 订单诊断节点 (order_diagnosis.py)
```python
# 关键实现点：
# 1. 思考过程的流式输出
# 2. 模拟订单信息查询和展示
# 3. 工具调用演示（mock tools）
# 4. 诊断结果生成
```

### 6. FastAPI 流式接口 (main.py)
```python
# 关键实现点：
# 1. Server-Sent Events (SSE) 实现
# 2. 异步流式响应
# 3. 会话管理
# 4. 错误处理和状态码
```

## 快速启动步骤

### 1. 环境准备
```bash
# 激活虚拟环境
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装依赖（已有 requirements.txt）
pip install -r requirements.txt
```

### 2. 启动 Ollama 服务
```bash
# 确保 Ollama 服务运行在 localhost:11434
ollama serve

# 拉取所需模型
ollama pull qwen3:8b
ollama pull deepseek-v3.1:671b-cloud
```

### 3. 配置 LangSmith（可选）
```bash
# 在 .env 文件中设置您的 LangSmith API Key
LANGCHAIN_API_KEY=your_actual_api_key_here
```

### 4. 运行项目
```bash
# 启动 FastAPI 服务
python src/main.py

# 或运行命令行对话程序
python src/cli_chat.py
```

## 测试用例

### 1. 命令行测试
```bash
python src/cli_chat.py
# 输入: "你好"
# 预期: 自然对话回复

# 输入: "我的订单12345有问题"
# 预期: 触发订单诊断流程
```

### 2. API 测试
```bash
curl -X POST "http://localhost:8200/chat/stream" \
  -H "Content-Type: application/json" \
  -d '{"message": "我的订单有问题", "session_id": "test_session"}'
```

## 关键技术点说明

### 1. 流式输出实现
- 使用 FastAPI 的 StreamingResponse
- 实现 Server-Sent Events 协议
- 异步生成器处理 LangGraph 输出

### 2. 状态管理
- LangGraph 状态图管理对话上下文
- 会话级别的状态持久化
- 节点间的数据传递机制

### 3. 模型集成
- Ollama 本地模型的异步调用
- 不同模型的角色分工（意图分析 vs 对话生成）
- 模型切换和负载均衡

### 4. 监控和调试
- LangSmith 集成用于链路追踪
- 结构化日志记录
- 性能指标收集

## 扩展建议

### 1. 功能扩展
- 添加更多意图类型（退款、投诉等）
- 实现真实的订单系统集成
- 添加多轮对话上下文管理

### 2. 性能优化
- 实现模型响应缓存
- 添加请求限流和熔断
- 优化流式输出的延迟

### 3. 部署优化
- Docker 容器化部署
- 添加健康检查和监控
- 实现水平扩展支持

这个实施指南为您提供了完整的项目搭建路径，您可以按照步骤逐步实现各个功能模块。