diff --git a/docs/superpowers/specs/2026-04-02-ai-agent-design.md b/docs/superpowers/specs/2026-04-02-ai-agent-design.md new file mode 100644 index 0000000..b546224 --- /dev/null +++ b/docs/superpowers/specs/2026-04-02-ai-agent-design.md @@ -0,0 +1,322 @@ +# 企业内部 AI Agent 设计方案 + +**日期**: 2026-04-02 +**状态**: 设计中 + +--- + +## 一、需求概述 + +### 1.1 背景 + +为企业内部设计开发 AI Agent 平台，用于： +- 智能助手/问答（查询政策、制度、流程文档） +- 业务流程自动化（审批、数据录入、报表生成） +- 数据分析/决策支持 +- 客户服务/工单处理 + +### 1.2 约束条件 + +- 大型企业（500-2000人） +- 完全私有化部署，数据不出公司 +- 开源 LLM（Qwen/LLaMA）在本地 GPU 运行 +- 多端访问：网页 + 嵌入现有后台 + 企业IM + API +- 全数据源接入：文档、数据库(SQL Server)、业务系统API、文件 +- 单租户架构（多租户后期考虑） + +--- + +## 二、整体架构 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 多端访问层 │ +│ (Web客户端 │ 嵌入现有后台 │ 企业IM(钉钉/飞书) │ REST API) │ +└─────────────────────────┬───────────────────────────────────────┘ + │ +┌─────────────────────────▼───────────────────────────────────────┐ +│ API 网关层 │ +│ (认证 · 鉴权 · 限流 · 日志) │ +└─────────────────────────┬───────────────────────────────────────┘ + │ +┌─────────────────────────▼───────────────────────────────────────┐ +│ LangChain Agent 编排层 │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ 问答 Agent │ │ 自动化 Agent │ │ 分析 Agent │ │ +│ │ (RAG+Vector) │ │ (RPA+Tools) │ │ (DB+API) │ │ +│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ +│ │ │ │ │ +│ ┌──────▼─────────────────▼─────────────────▼───────┐ │ +│ │ LangChain Core / LangGraph │ │ +│ │ (Agent Executor · Tool Router) │ │ +│ └─────────────────────────┬─────────────────────────┘ │ +└─────────────────────────────┼─────────────────────────────────────┘ + │ +┌─────────────────────────────▼─────────────────────────────────────┐ +│ 工具层 (Tools) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ SQL Svr │ │ HTTP API│ │File Parse│ │ RAG搜索 │ ... │ +│ │ Query │ │ Call │ │(Excel/ │ │ (向量检索)│ │ +│ │ │ │ │ │Word/PDF) │ │ │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ ┌──────────┐ ┌──────────┐ │ +│ │ Python │ │ Msg │ │ +│ │ Script │ │ Send │ │ +│ └──────────┘ └──────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 三、核心组件 + +| 组件 | 技术选型 | 职责 | +|------|---------|------| +| **Agent 框架** | LangChain / LangGraph | Agent 编排、推理循环、Tool 调度 | +| **RAG 引擎** | LangChain VectorStore + Embedding | 企业知识库检索 | +| **向量数据库** | Milvus | 文本向量存储与检索 | +| **Embedding 模型** | 本地 BGE / XInference | 文本向量化 | +| **LLM 推理** | vLLM + 本地 Qwen/LLaMA | 大语言模型推理 | +| **工具层** | LangChain Tools | DB查询、API调用、文件处理等 | +| **API 服务** | FastAPI | 对外接口、多端接入 | +| **任务队列** | Celery + Redis | 异步任务处理 | +| **主数据库** | SQL Server | Agent 记忆、对话历史、配置存储 | + +--- + +## 四、Router 设计 + +### 4.1 混合路由策略 + +采用 **规则 + 小模型 LLM 混合路由**，优先级： + +1. **规则优先匹配**：高频、明确意图（如"发邮件"、"查考勤"） +2. **小模型意图分类**：中频、可描述的意图 +3. **大模型路由兜底**：复杂、模糊意图 + +### 4.2 意图分类 + +| 意图类型 | 标识 | 示例 | +|---------|------|------| +| 问答类 | `qa` | "年假有多少天？"、"如何申请设备维修？" | +| 自动化类 | `automation` | "帮我给张三发邮件说会议改到下午3点" | +| 分析类 | `analysis` | "统计一下各部门本月报销金额" | + +### 4.3 路由实现伪代码 + +```python +def classify_intent(query: str) -> str: + """ + 规则优先，匹配则直接返回 + 未命中则调用小模型分类 + """ + # 规则匹配 + for rule in intent_rules: + if rule.matches(query): + return rule.intent + + # 小模型分类 + return llm_small.invoke( + f"判断意图类型：qa/automation/analysis\n问题：{query}" + ).content.strip() +``` + +### 4.4 插件化扩展 + +```python +class BaseAgent(ABC): + name: str + description: str + tools: list[BaseTool] + + @abstractmethod + def run(self, query: str) -> str: + pass + +class AgentRegistry: + _agents: dict[str, BaseAgent] = {} + + @classmethod + def register(cls, agent: BaseAgent): + cls._agents[agent.name] = agent +``` + +新增 Agent 只需： +```python +@AgentRegistry.register +class NewAgent(BaseAgent): + name = "new_agent" + description = "处理XXX类型问题" + tools = [tool1, tool2] +``` + +--- + +## 五、工具层设计 + +### 5.1 工具列表 + +| 工具 | 输入 | 输出 | 说明 | +|------|------|------|------| +| **MySQLQueryTool** | SQL 查询语句 | JSON 数组 | 只读查询，支持超时保护 | +| **HttpApiTool** | URL + Method + Body | JSON 响应 | 封装常见 HTTP 方法，自动重试 | +| **FileParserTool** | 文件路径 | 文本内容 | 支持 xlsx/docx/pdf/txt，自动提取结构化数据 | +| **RAGSearchTool** | 自然语言查询 | Top-K 相关文本块 | 配合向量库，返回知识库检索结果 | +| **PythonScriptTool** | 脚本内容 + 参数 | JSON 结果 | 沙箱执行，用于复杂数据处理 | +| **MessageSendTool** | 接收人 + 内容 + 渠道 | 发送状态 | 支持邮件/钉钉/飞书/企业微信 | + +### 5.2 工具架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Tools 层 │ +├─────────────┬─────────────┬─────────────┬─────────────────┤ +│ SQL Server │ HTTP API │ File Parse │ RAG Search │ +│ Query │ Call │ (Excel/ │ (Milvus) │ +│ │ │ Word/PDF) │ │ +├─────────────┼─────────────┼─────────────┼─────────────────┤ +│ Script Run │ Msg Send │ ...更多工具可扩展 │ +│ (Python) │ (邮件/IM) │ │ │ +└─────────────┴─────────────┴─────────────┴─────────────────┘ +``` + +--- + +## 六、数据流设计 + +### 6.1 用户查询完整流程 + +``` +用户输入 + │ + ▼ +┌─────────────┐ +│ FastAPI │ ← 限流、日志记录 +└──────┬──────┘ + │ + ▼ +┌─────────────┐ +│ Router │ ← 规则匹配 → 小模型分类 +└──────┬──────┘ + │ + ▼ +┌─────────────────────────────────────────┐ +│ LangGraph Agent │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ LLM (Qwen/LLaMA) │ │ +│ │ reasoning + tool calling │ │ +│ └───────────────┬─────────────────┘ │ +│ │ │ +│ ┌────────▼────────┐ │ +│ │ Tool Router │ │ +│ │ (选择合适的tool)│ │ +│ └────────┬────────┘ │ +│ │ │ +│ ┌────────▼────────┐ │ +│ │ Tool Executor │ │ +│ │ (并行执行tools) │ │ +│ └────────┬────────┘ │ +│ │ │ +│ ┌────────▼────────┐ │ +│ │ Response │ │ +│ │ Synthesizer │ │ +│ │ (整合tool结果) │ │ +│ └─────────────────┘ │ +└──────────────────┬──────────────────────┘ + │ + ▼ + ┌─────────────┐ + │ 返回用户 │ + └─────────────┘ +``` + +--- + +## 七、错误处理策略 + +| 错误类型 | 处理策略 | +|---------|---------| +| **LLM 超时/宕机** | 自动切换备用模型；返回"服务暂时不可用，请稍后重试" | +| **Tool 执行失败** | 重试 3 次 → 失败则返回错误信息 + 部分结果 | +| **数据库连接失败** | 返回"数据库暂时不可用"；记录错误日志 | +| **文件解析失败** | 返回"文件格式不支持或文件损坏" | +| **RAG 检索为空** | 返回"未找到相关内容，建议换个问法" | +| **恶意注入攻击** | SQL/指令注入检测；敏感操作需二次确认 | + +--- + +## 八、存储层设计 + +| 用途 | 技术选型 | 说明 | +|------|---------|------| +| **向量数据库** | Milvus | 企业文档向量存储，RAG 检索用 | +| **知识库原始文档** | MinIO / 本地文件系统 | 存储原始文档（PDF/Word/Excel） | +| **主业务数据库** | SQL Server | Agent 记忆、对话历史、配置存储 | +| **任务状态** | Redis + Celery | 异步任务队列、任务状态 | +| **日志存储** | Elasticsearch + Loki | 请求日志、Agent 执行日志 | + +--- + +## 九、部署架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 内网环境 │ +│ │ +│ ┌─────────────┐ │ +│ │ 用户端 │ ← Web / 嵌入后台 / 钉钉 / API │ +│ └──────┬──────┘ │ +│ │ │ +│ ┌──────▼──────┐ │ +│ │ FastAPI │ │ +│ └──────┬──────┘ │ +│ │ │ +│ ┌──────▼──────┐ │ +│ │ Router │ ← 规则 + 小模型混合路由 │ +│ └──────┬──────┘ │ +│ │ │ +│ ┌──────▼──────────────────────────────┐ │ +│ │ LangChain Agent 集群 │ │ +│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ +│ │ │ QA Agent │ │Auto Agent│ │Analysis │ │ │ +│ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ +│ └───────┼────────────┼────────────┼───────┘ │ +│ │ │ │ │ +│ ┌───────▼────────────▼────────────▼───────┐ │ +│ │ Tools 层 │ │ +│ │ (SQL Server │ API │ 文件解析 │ RAG) │ │ +│ └──────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ vLLM │ │ Milvus │ │ SQL Server │ │ +│ │ (LLM推理) │ │ (向量库) │ │ (主库) │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 十、技术选型总结 + +| 模块 | 技术选型 | +|------|---------| +| Agent 框架 | LangChain / LangGraph | +| Router | 规则 + 小模型混合意图分类 | +| Agent 类型 | QA Agent、Automation Agent、Analysis Agent | +| 工具层 | SQL Server 查询、HTTP API 调用、文件解析、RAG 检索、脚本执行、消息发送 | +| 向量库 | Milvus | +| LLM 推理 | vLLM + 本地 Qwen/LLaMA | +| 主数据库 | SQL Server | +| 任务队列 | Redis + Celery | +| 访问端 | Web + 嵌入后台 + 钉钉/飞书 + API | + +--- + +## 十一、后续步骤 + +1. 编写详细实现方案（implementation plan） +2. 确定开发优先级和里程碑 +3. 开始原型开发