ai-courseware/langchain-project/.trae/documents/implementation_guide.md

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)

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

3. LangGraph 工作流实现 (chat_workflow.py)

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

4. 意图分析节点 (intent_analysis.py)

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

5. 订单诊断节点 (order_diagnosis.py)

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

6. FastAPI 流式接口 (main.py)

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

快速启动步骤

1. 环境准备

# 激活虚拟环境
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

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

2. 启动 Ollama 服务

# 确保 Ollama 服务运行在 localhost:11434
ollama serve

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

3. 配置 LangSmith（可选）

# 在 .env 文件中设置您的 LangSmith API Key
LANGCHAIN_API_KEY=your_actual_api_key_here

4. 运行项目

# 启动 FastAPI 服务
python src/main.py

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

测试用例

1. 命令行测试

python src/cli_chat.py
# 输入: "你好"
# 预期: 自然对话回复

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

2. API 测试

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 容器化部署
• 添加健康检查和监控
• 实现水平扩展支持

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