1. 项目概述
这个项目构建了一个能够自主诊断设备故障的AI智能体(Agent)。不同于传统的问答机器人,这个系统能够像经验丰富的运维工程师一样,通过多步骤推理和工具调用,完成从故障现象分析到解决方案生成的完整流程。
核心功能包括:
- 接收用户描述的设备故障现象(如"制冰机报错E03")
- 自主查询设备实时状态
- 读取设备运行日志
- 检索知识库中的技术文档
- 综合分析后生成结构化的诊断报告
这个项目的独特之处在于它实现了真正的"智能代理"行为:
- 能够自主决定何时调用哪个工具
- 可以根据前一步的结果动态调整后续行动
- 整合多种信息来源进行综合判断
- 最终输出可执行的解决方案
2. 技术架构解析
2.1 整体技术栈
| 层级 | 技术选型 | 作用说明 |
|---|---|---|
| LLM层 | Claude/GPT-4o | 提供核心推理能力 |
| 框架层 | LangChain | 统一LLM应用开发接口 |
| Agent层 | LangGraph(ReAct) | Agent编排与决策引擎 |
| 知识库 | ChromaDB + Embedding | 实现文档检索功能 |
| API层 | FastAPI + SSE | 提供REST接口和流式输出 |
| 部署 | Docker + docker-compose | 实现一键部署 |
2.2 为什么选择这些技术
LangChain作为框架核心,主要解决了以下问题:
- 统一不同LLM提供商的接口
- 提供标准化的工具调用机制
- 内置常见模式(如RAG)的实现
LangGraph相比原生LangChain的AgentExecutor:
- 提供更灵活的Agent编排能力
- 支持更复杂的控制流
- 调试信息更丰富
ChromaDB作为向量数据库:
- 轻量级,适合开发环境
- 支持本地持久化
- 与LangChain深度集成
3. 核心模块实现
3.1 LLM基础接入
3.1.1 多模型统一接口
通过工厂模式实现不同LLM的无缝切换:
python复制def create_llm(provider: str = None):
"""根据provider创建对应的LLM实例"""
provider = provider or settings.DEFAULT_LLM_PROVIDER
if provider == "claude":
return ChatAnthropic(
model=settings.CLAUDE_MODEL,
api_key=settings.ANTHROPIC_API_KEY,
max_tokens=4096,
base_url=settings.ANTHROPIC_BASE_URL or None
)
elif provider == "openai":
return ChatOpenAI(
model=settings.OPENAI_MODEL,
api_key=settings.OPENAI_API_KEY,
base_url=settings.OPENAI_BASE_URL or None
)
3.1.2 消息历史管理
LangChain使用三种消息类型维护对话上下文:
python复制from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
messages = [
SystemMessage(content="你是一个设备诊断助手"), # 系统提示词
HumanMessage(content="制冰机报错了"), # 用户输入
AIMessage(content="请问是什么错误码?"), # AI回复
HumanMessage(content="E03"), # 用户继续
]
3.2 RAG知识库构建
3.2.1 文档处理流程
- 文档加载:支持PDF、Markdown、TXT格式
- 文本切分:采用递归字符分割器
- 向量化:使用HuggingFace的all-MiniLM-L6-v2模型
- 存储检索:存入ChromaDB向量数据库
3.2.2 关键参数选择
- chunk_size=1000:平衡检索精度和上下文完整性
- chunk_overlap=200:避免语义断裂
- 对Markdown采用二次切分策略:
- 先按标题切分
- 对过长章节再按字符切分
3.3 Agent系统实现
3.3.1 ReAct模式详解
ReAct = Reasoning + Acting,典型执行流程:
code复制Thought: 需要先查设备状态
Action: query_device_status("BAR-001")
Observation: 状态error,错误码E03
Thought: 需要查日志详情
Action: fetch_device_logs("middleware", keyword="E03")
Observation: 水泵压力异常
Thought: 需要查知识库
Action: search_knowledge_base("制冰机 E03")
Observation: 手册建议检查水泵
Thought: 生成报告
Action: generate_diagnosis_report(...)
Final Answer: 📋 诊断报告...
3.3.2 工具定义规范
使用@tool装饰器定义工具,description至关重要:
python复制@tool
def search_knowledge_base(query: str) -> str:
"""搜索设备知识库,查找设备手册、操作规范、故障案例等技术文档。
当需要查询设备的技术参数、操作流程、日志规范、错误码含义、
硬件接口说明等信息时使用此工具。
"""
# 实现略
3.3.3 日志读取双模式设计
支持本地和SSH两种模式,通过环境变量切换:
python复制@tool
def fetch_device_logs(log_type="syslog", lines=50, keyword="") -> str:
if settings.LOG_READ_MODE == "local":
return _read_local(log_type, lines, keyword) # 直接读文件
else:
return _read_ssh(log_type, lines, keyword) # SSH远程读取
4. 生产化部署
4.1 API服务设计
采用FastAPI实现以下端点:
| 方法 | 路径 | 功能 |
|---|---|---|
| POST | /api/chat | 普通对话 |
| POST | /api/chat/stream | 流式对话 |
| POST | /api/diagnose | Agent诊断 |
| POST | /api/diagnose/stream | 流式诊断 |
4.2 流式输出实现
使用SSE(Server-Sent Events)技术:
python复制async def event_generator():
for token in session.stream_chat(req.message):
yield f"data: {json.dumps({'token': token})}\n\n"
yield "data: {done: true}\n\n"
return StreamingResponse(event_generator(), media_type="text/event-stream")
4.3 Docker部署方案
Dockerfile关键配置:
dockerfile复制FROM python:3.11-slim
RUN apt-get update && apt-get install -y openssh-client
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0"]
5. 实战经验与避坑指南
5.1 常见问题解决
-
代理冲突问题:
- 现象:调用中转站API时出现SSL错误
- 解决:在settings.py中清除代理环境变量
-
流式输出降级:
- 现象:流式输出失败
- 解决:实现自动降级到非流式调用
-
工具选择不准:
- 现象:Agent频繁选错工具
- 解决:优化工具description,明确使用场景
5.2 性能优化建议
-
知识库检索优化:
- 实现BM25混合检索
- 加入CrossEncoder重排序
- 采用RRF融合算法
-
会话管理:
- 优先使用Redis持久化
- 自动降级到内存存储
-
API限流:
- 使用slowapi实现
- 按端点分级限制
6. 项目进阶方向
已实现的扩展功能包括:
- 真实设备API对接
- 前端界面开发(React+Vite)
- 多Agent协作系统
- 完整评估体系(Recall@K+MRR)
- RAG检索优化方案
7. 快速开始指南
bash复制# 克隆项目
git clone https://github.com/your-repo/ai-diagnostic-agent
cd ai-diagnostic-agent
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
# 配置环境
cp .env.example .env
# 编辑.env文件
# 构建知识库
python scripts/build_knowledge_base.py --local
# 启动服务
uvicorn src.api.app:app --reload
访问http://localhost:8000/docs查看API文档
