{"repo": "altergom/go-agent", "files": {"README.md": {"8575a1e1003d3068c4aafb472db9b9295dcb220e": {"t": 1785674252.672224, "n": 13217, "h": "1ecf4a4476317d67", "c": "# Go-Agent\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/github/go-mod/go-version/cloudwego/eino?style=flat-square&logo=go\" alt=\"Go Version\">\n  <img src=\"https://img.shields.io/badge/Framework-Eino-blue?style=flat-square\" alt=\"Framework\">\n  <img src=\"https://img.shields.io/badge/License-Apache--2.0-green?style=flat-square\" alt=\"License\">\n  <img src=\"https://img.shields.io/badge/Production-Ready-brightgreen?style=flat-square\" alt=\"Production Ready\">\n</p>\n\nGo-Agent 是一个基于 [CloudWeGo-Eino](https://github.com/cloudwego/eino) 构建的**生产级 AI Agent 应用开发框架**。它不仅是技术演示，更是一套完整的工程化解决方案，深度整合了 RAG、MCP、HITL、智能分析等企业级能力，为 **AI 应用落地与面试实战** 提供最佳实践参考。\n\n---\n\n## 🌟 核心特性\n\n### 🎯 智能编排引擎\n- **意图识别路由**：基于 Eino Graph 的 DAG/Pregel 双模式编排，自动识别用户意图并分发至对应的专业子图\n- **流程可视化**：支持复杂业务流程的图形化编排，状态可追溯、可恢复\n- **条件分支控制**：内置 Branch 节点和 Lambda 表达式，实现灵活的业务逻辑判断\n\n### 🔍 企业级 RAG 系统\n- **混合检索架构**：Milvus 向量检索 + Elasticsearch 全文检索 + BM25/RRF 融合排序\n- **多模态文档解析**：支持 PDF 中的文本、表格、图片混合提取与检索\n- **智能缓存层**：基于 Redis 的检索结果缓存，大幅降低重复查询的延迟与成本\n\n### 🤝 生产级人机协同 (HITL)\n- **中断-恢复机制**：支持 SQL 执行、敏感操作等场景的人工审批，审批后无缝恢复执行\n- **分布式状态持久化**：基于 Redis 的 CheckPoint 存储，服务重启后状态不丢失\n- **会话管理**：多会话隔离，支持长时间异步审批场景\n\n### 🔌 自建 MCP 工具服务器\n- **完整 CRUD 能力**：不再局限于只读查询，支持 INSERT/UPDATE/DELETE 及 DDL 操作\n- **多层安全防护**：SQL 白名单验证 + 危险模式拦截 + 强制 WHERE 子句 + 全链路审计日志\n- **审计与合规**：所有数据库操作自动记录到审计表，满足企业安全与合规要求\n\n### 📊 智能数据分析助手\n- **自动洞察生成**：SQL 执行完成后，AnalystAgent 自动进行统计分析、趋势识别、异常检测\n- **可视化配置输出**：基于数据特征智能推荐图表类型，生成开箱即用的 ECharts 配置\n- **自然语言报告**：将数据分析结果转化为业务可读的文字报告\n\n### 🔄 AI 自我进化闭环\n- **无侵入式数据采集**：通过 Callbacks 自动记录用户交互轨迹\n- **教师模型标注**：利用强模型对业务数据进行自动标注，构建高质量 SFT 语料\n- **持续优化迭代**：支持模型微调与效果评估的完整工作流\n\n### ⚡ 性能与成本优化\n- **投机采样加速**：Draft Model + Target Model 协同，降低推理延迟\n- **首字延迟优化 (TTFT)**：流式响应 + 并行处理，提升用户体验\n- **多模型配置**：支持按场景选择不同成本/能力的模型组合\n\n---\n\n## 🏗️ 系统架构\n\nGo-Agent 采用分层组件化架构，核心模块职责清晰、松耦合、高内聚：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      API 接入层                              │\n│   RESTful 路由 │ Session 管理 │ HITL 审批处理               │\n└────────────────────┬────────────────────────────────────────┘\n                     │\n┌────────────────────▼────────────────────────────────────────┐\n│                  编排引擎层 (Eino Graph)                     │\n│   意图路由 │ RAG Chat │ SQL React │ Analyst 子图            │\n└────────────────────┬────────────────────────────────────────┘\n                     │\n         ┌───────────┼───────────┐\n         ▼           ▼           ▼\n┌────────────┐ ┌──────────┐ ┌─────────────┐\n│ RAG 模块   │ │ MCP 工具 │ │ 数据分析    │\n│ 检索+召回  │ │ SQL执行  │ │ Analyst     │\n└──────┬─────┘ └────┬─────┘ └──────┬──────┘\n       │            │              │\n┌──────▼────────────▼──────────────▼──────────────────────────┐\n│                   基础设施层                                  │\n│ Redis (状态/缓存) │ Milvus/ES (检索) │ MySQL (审计/业务)    │\n│ LLM 工厂 (Ark/DeepSeek/Gemini/Qwen) │ Embedding 工厂       │\n└──────────────────────────────────────────────────────────────┘\n```\n\n**核心设计理念**：\n- **存储层分离**：状态、缓存、业务数据分别使用 Redis、向量库、关系型数据库\n- **模型工厂抽象**：统一接口，支持多厂商模型的配置化切换与成本优化\n- **子图可组合**：每个业务能力（RAG、SQL、分析）独立成图，可灵活组合编排\n\n---\n\n## 📂 项目结构\n\n```bash\n├── api/                    # 接入层：HTTP 路由、会话管理、HITL 审批接口\n├── flow/                   # 编排层：业务流程图定义 (意图路由/RAG/SQL/Analyst)\n├── model/                  # 模型工厂：多厂商 ChatModel 与 EmbeddingModel 适配\n│   ├── chat_model/         # 对话模型：Ark, DeepSeek, Gemini, OpenAI, Qwen\n│   └── embedding_model/    # 向量模型：含多模态 Embedding 支持\n├── rag/                    # RAG 核心：文档索引、混合检索、召回融合\n│   ├── rag_flow/           # 检索流程编排\n│   └── rag_tools/          # 工具组件（Indexer, Retriever, DB 连接器）\n├── tool/                   # 工具与工程化组件\n│   ├── storage/            # Redis 持久化层 (CheckPoint/Session/Cache)\n│   ├── sql_tools/          # MCP 客户端与 SQL 工具集成\n│   ├── analyst_tools/      # 数据分析工具集 (统计/图表生成)\n│   ├── document/           # 文档解析器 (含多模态 PDF 支持)\n│   ├── sft/                # SFT 数据采集与标注\n│   ├── memory/             # 对话记忆管理\n│   └── trace/              # 链路追踪与日志\n├── mcp_server/             # 自建 MCP 服务器 (CRUD + 安全审计)\n│   ├── tools/              # 工具实现 (query/insert/update/delete)\n│   └── security/           # 安全模块 (SQL 白名单 + 审计日志)\n├── config/                 # 配置管理：环境变量加载与全局配置\n├── test/                   # 测试套件：单元测试 + 性能基准测试\n└── main.go                 # 服务入口：组件初始化与启动\n```\n\n---\n\n## 🚀 快速开始\n\n### 前置要求\n\n- Go 1.21+\n- Docker & Docker Compose（用于快速部署依赖服务）\n- 至少一个 LLM 服务商的 API Key（Ark/OpenAI/DeepSeek/Gemini/Qwen）\n\n### 一、克隆项目\n\n```bash\ngit clone https://github.com/your-repo/go-agent.git\ncd go-agent\n```\n\n### 二、部署基础设施\n\n#### 1. 使用 Docker Compose 一键启动所有依赖服务\n\n```bash\ndocker-compose up -d\n```\n\n该命令将自动启动：\n- **Redis** (端口 6379)：用于状态持久化和缓存\n- **Milvus** (端口 19530)：向量数据库\n- **Elasticsearch** (端口 9200)：全文检索引擎\n- **MySQL** (端口 3306)：审计日志存储\n\n#### 2. 手动部署（可选）\n\n如果你想单独部署某个服务：\n\n**Redis**:\n```bash\ndocker run -d --name redis -p 6379:6379 redis:7-alpine\n```\n\n**Elasticsearch**:\n```bash\ndocker run -d --name elasticsearch \\\n  -p 9200:9200 \\\n  -e \"discovery.type=single-node\" \\\n  -e \"ES_JAVA_OPTS=-Xms512m -Xmx512m\" \\\n  elasticsearch:7.17.9\n```\n\n**Milvus**:\n```bash\nwget https://github.com/milvus-io/milvus/releases/download/v2.5.4/milvus-standalone-docker-compose.yml -O milvus-compose.yml\ndocker-compose -f milvus-compose.yml up -d\n```\n\n**MySQL** (用于审计日志):\n```bash\ndocker run -d --name mysql-audit \\\n  -p 3307:3306 \\\n  -e MYSQL_ROOT_PASSWORD=audit_password \\\n  -e MYSQL_DATABASE=go_agent_audit \\\n  mysql:8\n```\n\n### 三、配置环境变量\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env` 文件，填入你的配置：\n\n```env\n# ===== LLM 模型配置 =====\n# Ark (豆包)\nARK_KEY=your_ark_api_key\nARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3\n\n# OpenAI\nOPENAI_API_KEY=your_openai_key\nOPENAI_BASE_URL=https://api.openai.com/v1\n\n# DeepSeek\nDEEPSEEK_API_KEY=your_deepseek_key\nDEEPSEEK_BASE_URL=https://api.deepseek.com\n\n# Gemini\nGEMINI_API_KEY=your_gemini_key\n\n# Qwen (通义千问)\nQWEN_API_KEY=your_qwen_key\n\n# ===== Redis 配置 =====\nREDIS_ADDR=localhost:6379\nREDIS_PASSWORD=\nREDIS_DB=0\n\n# ===== Milvus 配置 =====\nMILVUS_ADDR=localhost:19530\nMILVUS_COLLECTION_NAME=GoAgent\n\n# ===== Elasticsearch 配置 =====\nES_ADDRESS=http://localhost:9200\nES_INDEX=go_agent_docs\n\n# ===== MySQL 审计数据库 =====\nAUDIT_MYSQL_HOST=localhost\nAUDIT_MYSQL_PORT=3307\nAUDIT_MYSQL_USER=root\nAUDIT_MYSQL_PASSWORD=audit_password\nAUDIT_MYSQL_DATABASE=go_agent_audit\n\n# ===== MCP 服务器配置 =====\nMCP_SERVER_PATH=./mcp_server/go-agent-mcp-server\nMCP_WHITELIST_PATH=./mcp_server/whitelist.yaml\n```\n\n### 四、安装依赖并启动\n\n```bash\n# 安装 Go 依赖\ngo mod tidy\n\n# (可选) 编译 MCP 服务器\ncd mcp_server\ngo build -o go-agent-mcp-server\ncd ..\n\n# 启动主服务\ngo run main.go\n```\n\n### 五、访问应用\n\n服务启动后，访问以下地址：\n\n- **完整对话界面**: http://localhost:8080/final_graph.html\n- **RAG 知识库管理**: http://localhost:8080/rag_knowledge.html\n- **文档索引**: http://localhost:8080/rag_index.html\n- **RAG 问答测试**: http://localhost:8080/rag_ask.html\n\n---\n\n## 📖 功能使用指南\n\n### 1. RAG 知识库构建\n\n#### 步骤 1: 上传文档\n\n访问 `http://localhost:8080/rag_index.html`，上传 PDF/TXT/Markdown 文档。\n\n支持的文档类型：\n- 纯文本文档\n- PDF（含文本、表格混合提取）\n- 多模态 PDF（图片提取与向量化）\n\n#### 步骤 2: 自动索引\n\n系统会自动：\n1. 解析文档内容\n2. 切分为语义块\n3. 生成 Embedding 向量\n4. 同时存入 Milvus（向量索引）和 Elasticsearch（全文索引）\n\n#### 步骤 3: 混合检索\n\n在对话或 RAG 问答中，系统会：\n- **向量检索**: 通过语义相似度召回相关文档\n- **全文检索**: 通过关键词匹配召回精确文档\n- **融合排序**: 使用 BM25 + RRF 算法融合两路结果\n\n### 2. SQL 数据库对话\n\n#### 自然语言查询\n\n用户：`帮我查询销售额最高的前5个产品`\n\n系统流程：\n1. **意图识别** → 识别为 SQL 查询意图\n2. **SQL 生成** → 调用 LLM 生成 SQL: `SELECT product_name, SUM(sales) FROM orders GROUP BY product_name ORDER BY SUM(sales) DESC LIMIT 5`\n3. **HITL 审批** → 中断流程，等待用户审批 SQL\n4. **执行与分析**:\n   - 用户批准后，通过 MCP 工具执行 SQL\n   - AnalystAgent 自动分析结果，生成统计报告\n   - 推荐柱状图，输出 ECharts 配置\n5. **返回结果** → 包含 SQL 结果 + 文字分析 + 图表配置\n\n#### 数据修改操作\n\n用户：`将产品ID为101的价格改为99.9`\n\n系统流程：\n1. 生成 SQL: `UPDATE products SET price = 99.9 WHERE id = 101`\n2. **安全校验**:\n   - MCP 服务器白名单验证\n   - 检测是否包含 WHERE 子句（强制要求）\n   - 审计日志记录\n3. **HITL 审批** → 敏感操作，必须人工确认\n4. **执行并记录** → 写入 `audit_log` 表\n\n#### 危险操作拦截\n\n用户：`清空整个订单表`\n\n系统流程：\n1. 生成 SQL: `TRUNCATE TABLE orders` 或 `DELETE FROM orders`\n2. **拦截机制**:\n   - 白名单检测到 `TRUNCATE` 或不含 WHERE 的 `DELETE`\n   - 拒绝执行，返回错误提示\n   - 审计日志记录拦截事件\n3. **用户提示** → \"该操作已被安全策略拦截，请联系管理员\"\n\n### 3. 人机协同审批 (HITL)\n\n#### 中断机制\n\n当系统需要人工介入时（如执行 SQL），会触发中断：\n\n```json\n{\n  \"status\": \"interrupted\",\n  \"checkpoint_id\": \"ckpt_abc123\",\n  \"session_id\": \"sess_xyz789\",\n  \"pending_action\": {\n    \"type\": \"sql_execution\",\n    \"sql\": \"UPDATE products SET price = 99.9 WHERE id = 101\",\n    \"reason\": \"需要审批数据修改操作\"\n  }\n}\n```\n\n#### 审批与恢复\n\n用户通过审批接口选择：\n\n**批准执行**:\n```bash\nPOST /api/approve\n{\n  \"session_id\": \"sess_xyz789\",\n  \"checkpoint_id\": \"ckpt_abc123\",\n  \"action\": \"approve\"\n}\n```\n\n系统会：\n1. 从 Redis 恢复 CheckPoint 状态\n2. 继续执行剩余流程\n3. 返回最终结果\n\n**拒绝执行**:\n```bash\nPOST /api/approve\n{\n  \"session_id\": \"sess_xyz789\",\n  \"checkpoint_id\": \"ckpt_abc123\",\n  \"action\": \"reject\",\n  \"reason\": \"SQL 语句有误\"\n}\n```\n\n系统会终止流程并返回拒绝原因。\n\n### 4. 智能数据分析\n\n#### 自动触发\n\n当 SQL 执行成功后，AnalystAgent 会自动启动分析流程。\n\n#### 分析能力\n\n1. **统计计算**:\n   - 均值、中位数、标准差\n   - 最大值、最小值、四分位数\n   - 数据分布特征\n\n2. **趋势识别**:\n   - 时间序列趋势（上升/下降/平稳）\n   - 周期性模式\n   - 异常值检测\n\n3. **图表推荐**:\n   - 数值型单列 → 推荐柱状图/折线图\n   - 分类占比 → 推荐饼图\n   - 时间序列 → 推荐折线图/面积图\n   - 多维对比 → 推荐分组柱状图\n\n4. **自然语言报告**:\n```\n数据分析结果：\n共返回5条记录，销售额范围在 1.2万 至 8.5万 之间，平均值为 4.3万。\n其中\"产品A\"表现最佳，销售额达到 8.5万，占比 42%。\n建议重点关注\"产品A\"的库存补充。\n```\n\n#### 响应格式\n\n```json\n{\n  \"query\": \"查询销售额最高的5个产品\",\n  \"answer\": \"已为您查询完成\",\n  \"sql_result\": \"[[\\\"产品A\\\", 85000], [\\\"产品B\\\", 62000], ...]\",\n  \"analysis\": \"数据分析结果：共返回5条记录...\",\n  \"chart_config\": {\n    \"type\": \"bar\",\n    \"xAxis\": { \"data\": [\"产品A\", \"产品B\", ...] },\n    \"yAxis\": {},\n    \"series\": [{ \"type\": \"bar\", \"data\": [85000, 62000, ...] }]\n  },\n  \"status\": \"completed\"\n}\n```\n\n---\n\n## 🔧 高级配置\n\n### 模型选择策略\n\n项目支持为不同场景配置不同的模型：\n\n```go\n// config/config.go\n\ntype ModelConfig struct {\n    // 对话模型（高质量）\n    ChatModel string // \"ark:ep-xxxxx\" | \"deepseek-chat\" | \"gpt-4\"\n    \n    // 快速模型（成本优化）\n    FastModel string // \"deepseek-chat\" | \"gpt-3.5-turbo\"\n    \n    // Draft 模型（投机采样）\n    DraftModel string // \"qwen-turbo\" | \"deepseek-coder\"\n    \n    // Embedding 模型\n    EmbeddingModel string // \"text-embedding-ada-002\" | \"ark-embedding\"\n}\n```\n配置方法为手动修改注册名(以意图识别模型为例)\n```\n// .env\n\nINTENT_MODEL_TYPE=ark\n```\n如果存在调用同一提供商的不同模型清仿照`// config/config.go`和`// model/chat_model`的实现手动添加不同配置\n\n### MCP 白名单定制\n\n编辑 `mcp_server/whitelist.yaml`:\n\n```yaml\nallowed_operations:\n  - SELECT\n  - INSERT\n  - UPDATE\n  - DELETE\n  - CREATE TABLE\n  - ALTER TABLE\n\nforbidden_patterns:\n  - DROP DATABASE\n  - DROP TABLE\n  - TRUNCATE\n  - LOAD_FILE\n  - INTO OUTFILE\n  - UNION.*SELECT  # 防止 SQL 注入\n\nrequire_where_clause:\n  - UPDATE\n  - DELETE\n\naudit_level:\n  SELECT: info\n  INSERT: warning\n  UPDATE: warning\n  DELETE: error\n  CREATE: error\n  ALTER: error\n```\n\n### 性能优化参数\n\n```env\n# 缓存 TTL\nCACHE_RETRIEVAL_TTL=3600      # 检索缓存 1 小时\nCACHE_EMBEDDING_TTL=86400     # Embedding 缓存 24 小时\n\n# 检索参数\nRAG_TOP_K=10                  # 召回文档数量\nRAG_RERANK_TOP_K=5           # 重排序后保留数量\n\n# 并发控制\nMAX_CONCURRENT_REQUESTS=50    # 最大并发请求数\nGRAPH_TIMEOUT=300             # Graph 执行超时时间（秒）\n```\n\n---\n\n## 📊 监控与运维\n\n### 审计日志查询\n\n所有数据库操作都记录在 `audit_log` 表中：\n\n```sql\n-- 查看最近的 SQL 执行记录\nSELECT * FROM audit_log ORDER BY timestamp DESC LIMIT 20;\n\n-- 统计操作类型分布\nSELECT operation_type, COUNT(*) as count \nFROM audit_log \nGROUP BY operation_type;\n\n-- 查询失败的操作\nSELECT * FROM audit_log WHERE status = 'failed';\n\n-- 查询某个会话的所有操作\nSELECT * FROM audit_log WHERE session_id = 'sess_xyz789';\n```\n\n### 性能指标\n\n项目内置性能追踪，关键指标：\n\n- **TTFT (Time To First Token)**: 首字延迟，目标 < 1s\n- **检索延迟**: P99 < 500ms（缓存命中时）\n- **缓存命中率**: 目标 > 60%\n- **Graph 执行时间**: 完整流程 < 10s\n\n### 日志级别\n\n```env\nLOG_LEVEL=info  # debug | info | warning | error\nLOG_FORMAT=json # json | text\n```\n\n\n## 📖 技术深潜 (面向面试与实战)\n\n本项目针对大模型面试中的常见场景题提供了参考实现：\n\n### 1. Agent 如何解决一致性问题？\n\n**痛点**: 多轮对话中状态混乱、工具调用结果丢失\n\n**解决方案**:\n- **类型安全的状态管理**: 使用 Eino 的强类型 State，编译期检查\n- **CheckPoint 持久化**: 每次状态变更都写入 Redis，服务重启不丢失\n- **会话隔离**: 每个用户会话独立管理，互不干扰\n\n### 2. 如何处理长文本检索的精度问题？\n\n**痛点**: 向量检索容易召回不相关文档，关键词检索容易遗漏\n\n**解决方案**:\n- **混合检索**: 向量检索 + 全文检索并行\n- **融合排序**: BM25 + RRF 算法综合两路结果\n- **Query Rewriting**: 在检索前改写查询，提升召回率\n- **智能缓存**: 相似查询直接命中缓存，避免重复计算\n\n### 3. 如何低成本提升模型能力？\n\n**痛点**: 业务场景特殊，通用模型效果差，但标注数据成本高\n\n**解决方案**:\n- **自动数据采集**: Callbacks 机制无侵入式记录用户交互\n- **教师模型标注**: 用 GPT-4/DeepSeek-V3 对业务数据自动打标\n- **SFT 闭环**: 定期微调小模型，降低推理成本\n- **效果评估**: A/B 测试验证微调效果\n\n### 4. 如何优化高并发下的响应体验？\n\n**痛点**: 强模型推理慢，用户等待时间长\n\n**解决方案**:\n- **投机采样**: 用快速小模型生成 Draft，强模型验证\n- **流式响应**: Server-Sent Events (SSE) 实时返回 Token\n- **并行处理**: 检索、Embedding、工具调用并行执行\n- **多级缓存**: Redis 缓存 + 应用内存缓存\n\n### 5. 如何保障 Agent 的安全性？\n\n**痛点**: Agent 可能执行危险操作，如删库、泄露数据\n\n**解决方案**:\n- **HITL 机制**: 敏感操作必须人工审批\n- **SQL 白名单**: 只允许配置的操作类型\n- **危险模式拦截**: 正则 + AST 解析双重检测\n- **全链路审计**: 所有操作记录可追溯\n- **权限隔离**: 数据库账号最小权限原则\n\n---\n\n## 🤝 贡献指南\n\n我们欢迎任何形式的贡献！\n\n### 提交 Issue\n\n- **Bug 报告**: 请详细描述复现步骤、环境信息、错误日志\n- **功能请求**: 请说明使用场景、预期效果、优先级\n\n### 提交 Pull Request\n\n1. Fork 本仓库\n2. 创建特性分支: `git checkout -b feature/amazing-feature`\n3. 提交代码: `git commit -m 'Add amazing feature'`\n4. 推送分支: `git push origin feature/amazing-feature`\n5. 提交 PR\n\n**代码规范**:\n- 遵循 [Effective Go](https://golang.org/doc/effective_go) 规范\n- 添加必要的单元测试\n- 更新相关文档\n\n---\n\n## 📚 相关文档(持续更新ing)\n\n- **[依赖安装](./DEPENDENCIES.md)**: 所有依赖项的详细安装指南\n- **[HITL 机制踩坑](./doc/HITL机制踩坑复盘.md)**: 人机协同实现的实战经验(所谓“你遇到过什么困难”)\n\n---\n\n## 📜 许可证\n\n本项目基于 [Apache-2.0](./LICENSE) 协议开源。\n\n---\n\n## 📞 联系与支持\n\n- **Email**: kele3325@gmail.com\n- **Issues**: [GitHub Issues](https://github.com/altergom/go-agent/issues)\n\n---\n\n<p align=\"center\">\n  <strong>祝大家2026offer多多福满年❤️</strong><br>\n</p>\n"}, "c9e562bcbb0a02c06f901e2dddd929f8258e29e7": {"t": 1785766581.513449, "n": 13217, "h": "1ecf4a4476317d67", "c": "# Go-Agent\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/github/go-mod/go-version/cloudwego/eino?style=flat-square&logo=go\" alt=\"Go Version\">\n  <img src=\"https://img.shields.io/badge/Framework-Eino-blue?style=flat-square\" alt=\"Framework\">\n  <img src=\"https://img.shields.io/badge/License-Apache--2.0-green?style=flat-square\" alt=\"License\">\n  <img src=\"https://img.shields.io/badge/Production-Ready-brightgreen?style=flat-square\" alt=\"Production Ready\">\n</p>\n\nGo-Agent 是一个基于 [CloudWeGo-Eino](https://github.com/cloudwego/eino) 构建的**生产级 AI Agent 应用开发框架**。它不仅是技术演示，更是一套完整的工程化解决方案，深度整合了 RAG、MCP、HITL、智能分析等企业级能力，为 **AI 应用落地与面试实战** 提供最佳实践参考。\n\n---\n\n## 🌟 核心特性\n\n### 🎯 智能编排引擎\n- **意图识别路由**：基于 Eino Graph 的 DAG/Pregel 双模式编排，自动识别用户意图并分发至对应的专业子图\n- **流程可视化**：支持复杂业务流程的图形化编排，状态可追溯、可恢复\n- **条件分支控制**：内置 Branch 节点和 Lambda 表达式，实现灵活的业务逻辑判断\n\n### 🔍 企业级 RAG 系统\n- **混合检索架构**：Milvus 向量检索 + Elasticsearch 全文检索 + BM25/RRF 融合排序\n- **多模态文档解析**：支持 PDF 中的文本、表格、图片混合提取与检索\n- **智能缓存层**：基于 Redis 的检索结果缓存，大幅降低重复查询的延迟与成本\n\n### 🤝 生产级人机协同 (HITL)\n- **中断-恢复机制**：支持 SQL 执行、敏感操作等场景的人工审批，审批后无缝恢复执行\n- **分布式状态持久化**：基于 Redis 的 CheckPoint 存储，服务重启后状态不丢失\n- **会话管理**：多会话隔离，支持长时间异步审批场景\n\n### 🔌 自建 MCP 工具服务器\n- **完整 CRUD 能力**：不再局限于只读查询，支持 INSERT/UPDATE/DELETE 及 DDL 操作\n- **多层安全防护**：SQL 白名单验证 + 危险模式拦截 + 强制 WHERE 子句 + 全链路审计日志\n- **审计与合规**：所有数据库操作自动记录到审计表，满足企业安全与合规要求\n\n### 📊 智能数据分析助手\n- **自动洞察生成**：SQL 执行完成后，AnalystAgent 自动进行统计分析、趋势识别、异常检测\n- **可视化配置输出**：基于数据特征智能推荐图表类型，生成开箱即用的 ECharts 配置\n- **自然语言报告**：将数据分析结果转化为业务可读的文字报告\n\n### 🔄 AI 自我进化闭环\n- **无侵入式数据采集**：通过 Callbacks 自动记录用户交互轨迹\n- **教师模型标注**：利用强模型对业务数据进行自动标注，构建高质量 SFT 语料\n- **持续优化迭代**：支持模型微调与效果评估的完整工作流\n\n### ⚡ 性能与成本优化\n- **投机采样加速**：Draft Model + Target Model 协同，降低推理延迟\n- **首字延迟优化 (TTFT)**：流式响应 + 并行处理，提升用户体验\n- **多模型配置**：支持按场景选择不同成本/能力的模型组合\n\n---\n\n## 🏗️ 系统架构\n\nGo-Agent 采用分层组件化架构，核心模块职责清晰、松耦合、高内聚：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      API 接入层                              │\n│   RESTful 路由 │ Session 管理 │ HITL 审批处理               │\n└────────────────────┬────────────────────────────────────────┘\n                     │\n┌────────────────────▼────────────────────────────────────────┐\n│                  编排引擎层 (Eino Graph)                     │\n│   意图路由 │ RAG Chat │ SQL React │ Analyst 子图            │\n└────────────────────┬────────────────────────────────────────┘\n                     │\n         ┌───────────┼───────────┐\n         ▼           ▼           ▼\n┌────────────┐ ┌──────────┐ ┌─────────────┐\n│ RAG 模块   │ │ MCP 工具 │ │ 数据分析    │\n│ 检索+召回  │ │ SQL执行  │ │ Analyst     │\n└──────┬─────┘ └────┬─────┘ └──────┬──────┘\n       │            │              │\n┌──────▼────────────▼──────────────▼──────────────────────────┐\n│                   基础设施层                                  │\n│ Redis (状态/缓存) │ Milvus/ES (检索) │ MySQL (审计/业务)    │\n│ LLM 工厂 (Ark/DeepSeek/Gemini/Qwen) │ Embedding 工厂       │\n└──────────────────────────────────────────────────────────────┘\n```\n\n**核心设计理念**：\n- **存储层分离**：状态、缓存、业务数据分别使用 Redis、向量库、关系型数据库\n- **模型工厂抽象**：统一接口，支持多厂商模型的配置化切换与成本优化\n- **子图可组合**：每个业务能力（RAG、SQL、分析）独立成图，可灵活组合编排\n\n---\n\n## 📂 项目结构\n\n```bash\n├── api/                    # 接入层：HTTP 路由、会话管理、HITL 审批接口\n├── flow/                   # 编排层：业务流程图定义 (意图路由/RAG/SQL/Analyst)\n├── model/                  # 模型工厂：多厂商 ChatModel 与 EmbeddingModel 适配\n│   ├── chat_model/         # 对话模型：Ark, DeepSeek, Gemini, OpenAI, Qwen\n│   └── embedding_model/    # 向量模型：含多模态 Embedding 支持\n├── rag/                    # RAG 核心：文档索引、混合检索、召回融合\n│   ├── rag_flow/           # 检索流程编排\n│   └── rag_tools/          # 工具组件（Indexer, Retriever, DB 连接器）\n├── tool/                   # 工具与工程化组件\n│   ├── storage/            # Redis 持久化层 (CheckPoint/Session/Cache)\n│   ├── sql_tools/          # MCP 客户端与 SQL 工具集成\n│   ├── analyst_tools/      # 数据分析工具集 (统计/图表生成)\n│   ├── document/           # 文档解析器 (含多模态 PDF 支持)\n│   ├── sft/                # SFT 数据采集与标注\n│   ├── memory/             # 对话记忆管理\n│   └── trace/              # 链路追踪与日志\n├── mcp_server/             # 自建 MCP 服务器 (CRUD + 安全审计)\n│   ├── tools/              # 工具实现 (query/insert/update/delete)\n│   └── security/           # 安全模块 (SQL 白名单 + 审计日志)\n├── config/                 # 配置管理：环境变量加载与全局配置\n├── test/                   # 测试套件：单元测试 + 性能基准测试\n└── main.go                 # 服务入口：组件初始化与启动\n```\n\n---\n\n## 🚀 快速开始\n\n### 前置要求\n\n- Go 1.21+\n- Docker & Docker Compose（用于快速部署依赖服务）\n- 至少一个 LLM 服务商的 API Key（Ark/OpenAI/DeepSeek/Gemini/Qwen）\n\n### 一、克隆项目\n\n```bash\ngit clone https://github.com/your-repo/go-agent.git\ncd go-agent\n```\n\n### 二、部署基础设施\n\n#### 1. 使用 Docker Compose 一键启动所有依赖服务\n\n```bash\ndocker-compose up -d\n```\n\n该命令将自动启动：\n- **Redis** (端口 6379)：用于状态持久化和缓存\n- **Milvus** (端口 19530)：向量数据库\n- **Elasticsearch** (端口 9200)：全文检索引擎\n- **MySQL** (端口 3306)：审计日志存储\n\n#### 2. 手动部署（可选）\n\n如果你想单独部署某个服务：\n\n**Redis**:\n```bash\ndocker run -d --name redis -p 6379:6379 redis:7-alpine\n```\n\n**Elasticsearch**:\n```bash\ndocker run -d --name elasticsearch \\\n  -p 9200:9200 \\\n  -e \"discovery.type=single-node\" \\\n  -e \"ES_JAVA_OPTS=-Xms512m -Xmx512m\" \\\n  elasticsearch:7.17.9\n```\n\n**Milvus**:\n```bash\nwget https://github.com/milvus-io/milvus/releases/download/v2.5.4/milvus-standalone-docker-compose.yml -O milvus-compose.yml\ndocker-compose -f milvus-compose.yml up -d\n```\n\n**MySQL** (用于审计日志):\n```bash\ndocker run -d --name mysql-audit \\\n  -p 3307:3306 \\\n  -e MYSQL_ROOT_PASSWORD=audit_password \\\n  -e MYSQL_DATABASE=go_agent_audit \\\n  mysql:8\n```\n\n### 三、配置环境变量\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env` 文件，填入你的配置：\n\n```env\n# ===== LLM 模型配置 =====\n# Ark (豆包)\nARK_KEY=your_ark_api_key\nARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3\n\n# OpenAI\nOPENAI_API_KEY=your_openai_key\nOPENAI_BASE_URL=https://api.openai.com/v1\n\n# DeepSeek\nDEEPSEEK_API_KEY=your_deepseek_key\nDEEPSEEK_BASE_URL=https://api.deepseek.com\n\n# Gemini\nGEMINI_API_KEY=your_gemini_key\n\n# Qwen (通义千问)\nQWEN_API_KEY=your_qwen_key\n\n# ===== Redis 配置 =====\nREDIS_ADDR=localhost:6379\nREDIS_PASSWORD=\nREDIS_DB=0\n\n# ===== Milvus 配置 =====\nMILVUS_ADDR=localhost:19530\nMILVUS_COLLECTION_NAME=GoAgent\n\n# ===== Elasticsearch 配置 =====\nES_ADDRESS=http://localhost:9200\nES_INDEX=go_agent_docs\n\n# ===== MySQL 审计数据库 =====\nAUDIT_MYSQL_HOST=localhost\nAUDIT_MYSQL_PORT=3307\nAUDIT_MYSQL_USER=root\nAUDIT_MYSQL_PASSWORD=audit_password\nAUDIT_MYSQL_DATABASE=go_agent_audit\n\n# ===== MCP 服务器配置 =====\nMCP_SERVER_PATH=./mcp_server/go-agent-mcp-server\nMCP_WHITELIST_PATH=./mcp_server/whitelist.yaml\n```\n\n### 四、安装依赖并启动\n\n```bash\n# 安装 Go 依赖\ngo mod tidy\n\n# (可选) 编译 MCP 服务器\ncd mcp_server\ngo build -o go-agent-mcp-server\ncd ..\n\n# 启动主服务\ngo run main.go\n```\n\n### 五、访问应用\n\n服务启动后，访问以下地址：\n\n- **完整对话界面**: http://localhost:8080/final_graph.html\n- **RAG 知识库管理**: http://localhost:8080/rag_knowledge.html\n- **文档索引**: http://localhost:8080/rag_index.html\n- **RAG 问答测试**: http://localhost:8080/rag_ask.html\n\n---\n\n## 📖 功能使用指南\n\n### 1. RAG 知识库构建\n\n#### 步骤 1: 上传文档\n\n访问 `http://localhost:8080/rag_index.html`，上传 PDF/TXT/Markdown 文档。\n\n支持的文档类型：\n- 纯文本文档\n- PDF（含文本、表格混合提取）\n- 多模态 PDF（图片提取与向量化）\n\n#### 步骤 2: 自动索引\n\n系统会自动：\n1. 解析文档内容\n2. 切分为语义块\n3. 生成 Embedding 向量\n4. 同时存入 Milvus（向量索引）和 Elasticsearch（全文索引）\n\n#### 步骤 3: 混合检索\n\n在对话或 RAG 问答中，系统会：\n- **向量检索**: 通过语义相似度召回相关文档\n- **全文检索**: 通过关键词匹配召回精确文档\n- **融合排序**: 使用 BM25 + RRF 算法融合两路结果\n\n### 2. SQL 数据库对话\n\n#### 自然语言查询\n\n用户：`帮我查询销售额最高的前5个产品`\n\n系统流程：\n1. **意图识别** → 识别为 SQL 查询意图\n2. **SQL 生成** → 调用 LLM 生成 SQL: `SELECT product_name, SUM(sales) FROM orders GROUP BY product_name ORDER BY SUM(sales) DESC LIMIT 5`\n3. **HITL 审批** → 中断流程，等待用户审批 SQL\n4. **执行与分析**:\n   - 用户批准后，通过 MCP 工具执行 SQL\n   - AnalystAgent 自动分析结果，生成统计报告\n   - 推荐柱状图，输出 ECharts 配置\n5. **返回结果** → 包含 SQL 结果 + 文字分析 + 图表配置\n\n#### 数据修改操作\n\n用户：`将产品ID为101的价格改为99.9`\n\n系统流程：\n1. 生成 SQL: `UPDATE products SET price = 99.9 WHERE id = 101`\n2. **安全校验**:\n   - MCP 服务器白名单验证\n   - 检测是否包含 WHERE 子句（强制要求）\n   - 审计日志记录\n3. **HITL 审批** → 敏感操作，必须人工确认\n4. **执行并记录** → 写入 `audit_log` 表\n\n#### 危险操作拦截\n\n用户：`清空整个订单表`\n\n系统流程：\n1. 生成 SQL: `TRUNCATE TABLE orders` 或 `DELETE FROM orders`\n2. **拦截机制**:\n   - 白名单检测到 `TRUNCATE` 或不含 WHERE 的 `DELETE`\n   - 拒绝执行，返回错误提示\n   - 审计日志记录拦截事件\n3. **用户提示** → \"该操作已被安全策略拦截，请联系管理员\"\n\n### 3. 人机协同审批 (HITL)\n\n#### 中断机制\n\n当系统需要人工介入时（如执行 SQL），会触发中断：\n\n```json\n{\n  \"status\": \"interrupted\",\n  \"checkpoint_id\": \"ckpt_abc123\",\n  \"session_id\": \"sess_xyz789\",\n  \"pending_action\": {\n    \"type\": \"sql_execution\",\n    \"sql\": \"UPDATE products SET price = 99.9 WHERE id = 101\",\n    \"reason\": \"需要审批数据修改操作\"\n  }\n}\n```\n\n#### 审批与恢复\n\n用户通过审批接口选择：\n\n**批准执行**:\n```bash\nPOST /api/approve\n{\n  \"session_id\": \"sess_xyz789\",\n  \"checkpoint_id\": \"ckpt_abc123\",\n  \"action\": \"approve\"\n}\n```\n\n系统会：\n1. 从 Redis 恢复 CheckPoint 状态\n2. 继续执行剩余流程\n3. 返回最终结果\n\n**拒绝执行**:\n```bash\nPOST /api/approve\n{\n  \"session_id\": \"sess_xyz789\",\n  \"checkpoint_id\": \"ckpt_abc123\",\n  \"action\": \"reject\",\n  \"reason\": \"SQL 语句有误\"\n}\n```\n\n系统会终止流程并返回拒绝原因。\n\n### 4. 智能数据分析\n\n#### 自动触发\n\n当 SQL 执行成功后，AnalystAgent 会自动启动分析流程。\n\n#### 分析能力\n\n1. **统计计算**:\n   - 均值、中位数、标准差\n   - 最大值、最小值、四分位数\n   - 数据分布特征\n\n2. **趋势识别**:\n   - 时间序列趋势（上升/下降/平稳）\n   - 周期性模式\n   - 异常值检测\n\n3. **图表推荐**:\n   - 数值型单列 → 推荐柱状图/折线图\n   - 分类占比 → 推荐饼图\n   - 时间序列 → 推荐折线图/面积图\n   - 多维对比 → 推荐分组柱状图\n\n4. **自然语言报告**:\n```\n数据分析结果：\n共返回5条记录，销售额范围在 1.2万 至 8.5万 之间，平均值为 4.3万。\n其中\"产品A\"表现最佳，销售额达到 8.5万，占比 42%。\n建议重点关注\"产品A\"的库存补充。\n```\n\n#### 响应格式\n\n```json\n{\n  \"query\": \"查询销售额最高的5个产品\",\n  \"answer\": \"已为您查询完成\",\n  \"sql_result\": \"[[\\\"产品A\\\", 85000], [\\\"产品B\\\", 62000], ...]\",\n  \"analysis\": \"数据分析结果：共返回5条记录...\",\n  \"chart_config\": {\n    \"type\": \"bar\",\n    \"xAxis\": { \"data\": [\"产品A\", \"产品B\", ...] },\n    \"yAxis\": {},\n    \"series\": [{ \"type\": \"bar\", \"data\": [85000, 62000, ...] }]\n  },\n  \"status\": \"completed\"\n}\n```\n\n---\n\n## 🔧 高级配置\n\n### 模型选择策略\n\n项目支持为不同场景配置不同的模型：\n\n```go\n// config/config.go\n\ntype ModelConfig struct {\n    // 对话模型（高质量）\n    ChatModel string // \"ark:ep-xxxxx\" | \"deepseek-chat\" | \"gpt-4\"\n    \n    // 快速模型（成本优化）\n    FastModel string // \"deepseek-chat\" | \"gpt-3.5-turbo\"\n    \n    // Draft 模型（投机采样）\n    DraftModel string // \"qwen-turbo\" | \"deepseek-coder\"\n    \n    // Embedding 模型\n    EmbeddingModel string // \"text-embedding-ada-002\" | \"ark-embedding\"\n}\n```\n配置方法为手动修改注册名(以意图识别模型为例)\n```\n// .env\n\nINTENT_MODEL_TYPE=ark\n```\n如果存在调用同一提供商的不同模型清仿照`// config/config.go`和`// model/chat_model`的实现手动添加不同配置\n\n### MCP 白名单定制\n\n编辑 `mcp_server/whitelist.yaml`:\n\n```yaml\nallowed_operations:\n  - SELECT\n  - INSERT\n  - UPDATE\n  - DELETE\n  - CREATE TABLE\n  - ALTER TABLE\n\nforbidden_patterns:\n  - DROP DATABASE\n  - DROP TABLE\n  - TRUNCATE\n  - LOAD_FILE\n  - INTO OUTFILE\n  - UNION.*SELECT  # 防止 SQL 注入\n\nrequire_where_clause:\n  - UPDATE\n  - DELETE\n\naudit_level:\n  SELECT: info\n  INSERT: warning\n  UPDATE: warning\n  DELETE: error\n  CREATE: error\n  ALTER: error\n```\n\n### 性能优化参数\n\n```env\n# 缓存 TTL\nCACHE_RETRIEVAL_TTL=3600      # 检索缓存 1 小时\nCACHE_EMBEDDING_TTL=86400     # Embedding 缓存 24 小时\n\n# 检索参数\nRAG_TOP_K=10                  # 召回文档数量\nRAG_RERANK_TOP_K=5           # 重排序后保留数量\n\n# 并发控制\nMAX_CONCURRENT_REQUESTS=50    # 最大并发请求数\nGRAPH_TIMEOUT=300             # Graph 执行超时时间（秒）\n```\n\n---\n\n## 📊 监控与运维\n\n### 审计日志查询\n\n所有数据库操作都记录在 `audit_log` 表中：\n\n```sql\n-- 查看最近的 SQL 执行记录\nSELECT * FROM audit_log ORDER BY timestamp DESC LIMIT 20;\n\n-- 统计操作类型分布\nSELECT operation_type, COUNT(*) as count \nFROM audit_log \nGROUP BY operation_type;\n\n-- 查询失败的操作\nSELECT * FROM audit_log WHERE status = 'failed';\n\n-- 查询某个会话的所有操作\nSELECT * FROM audit_log WHERE session_id = 'sess_xyz789';\n```\n\n### 性能指标\n\n项目内置性能追踪，关键指标：\n\n- **TTFT (Time To First Token)**: 首字延迟，目标 < 1s\n- **检索延迟**: P99 < 500ms（缓存命中时）\n- **缓存命中率**: 目标 > 60%\n- **Graph 执行时间**: 完整流程 < 10s\n\n### 日志级别\n\n```env\nLOG_LEVEL=info  # debug | info | warning | error\nLOG_FORMAT=json # json | text\n```\n\n\n## 📖 技术深潜 (面向面试与实战)\n\n本项目针对大模型面试中的常见场景题提供了参考实现：\n\n### 1. Agent 如何解决一致性问题？\n\n**痛点**: 多轮对话中状态混乱、工具调用结果丢失\n\n**解决方案**:\n- **类型安全的状态管理**: 使用 Eino 的强类型 State，编译期检查\n- **CheckPoint 持久化**: 每次状态变更都写入 Redis，服务重启不丢失\n- **会话隔离**: 每个用户会话独立管理，互不干扰\n\n### 2. 如何处理长文本检索的精度问题？\n\n**痛点**: 向量检索容易召回不相关文档，关键词检索容易遗漏\n\n**解决方案**:\n- **混合检索**: 向量检索 + 全文检索并行\n- **融合排序**: BM25 + RRF 算法综合两路结果\n- **Query Rewriting**: 在检索前改写查询，提升召回率\n- **智能缓存**: 相似查询直接命中缓存，避免重复计算\n\n### 3. 如何低成本提升模型能力？\n\n**痛点**: 业务场景特殊，通用模型效果差，但标注数据成本高\n\n**解决方案**:\n- **自动数据采集**: Callbacks 机制无侵入式记录用户交互\n- **教师模型标注**: 用 GPT-4/DeepSeek-V3 对业务数据自动打标\n- **SFT 闭环**: 定期微调小模型，降低推理成本\n- **效果评估**: A/B 测试验证微调效果\n\n### 4. 如何优化高并发下的响应体验？\n\n**痛点**: 强模型推理慢，用户等待时间长\n\n**解决方案**:\n- **投机采样**: 用快速小模型生成 Draft，强模型验证\n- **流式响应**: Server-Sent Events (SSE) 实时返回 Token\n- **并行处理**: 检索、Embedding、工具调用并行执行\n- **多级缓存**: Redis 缓存 + 应用内存缓存\n\n### 5. 如何保障 Agent 的安全性？\n\n**痛点**: Agent 可能执行危险操作，如删库、泄露数据\n\n**解决方案**:\n- **HITL 机制**: 敏感操作必须人工审批\n- **SQL 白名单**: 只允许配置的操作类型\n- **危险模式拦截**: 正则 + AST 解析双重检测\n- **全链路审计**: 所有操作记录可追溯\n- **权限隔离**: 数据库账号最小权限原则\n\n---\n\n## 🤝 贡献指南\n\n我们欢迎任何形式的贡献！\n\n### 提交 Issue\n\n- **Bug 报告**: 请详细描述复现步骤、环境信息、错误日志\n- **功能请求**: 请说明使用场景、预期效果、优先级\n\n### 提交 Pull Request\n\n1. Fork 本仓库\n2. 创建特性分支: `git checkout -b feature/amazing-feature`\n3. 提交代码: `git commit -m 'Add amazing feature'`\n4. 推送分支: `git push origin feature/amazing-feature`\n5. 提交 PR\n\n**代码规范**:\n- 遵循 [Effective Go](https://golang.org/doc/effective_go) 规范\n- 添加必要的单元测试\n- 更新相关文档\n\n---\n\n## 📚 相关文档(持续更新ing)\n\n- **[依赖安装](./DEPENDENCIES.md)**: 所有依赖项的详细安装指南\n- **[HITL 机制踩坑](./doc/HITL机制踩坑复盘.md)**: 人机协同实现的实战经验(所谓“你遇到过什么困难”)\n\n---\n\n## 📜 许可证\n\n本项目基于 [Apache-2.0](./LICENSE) 协议开源。\n\n---\n\n## 📞 联系与支持\n\n- **Email**: kele3325@gmail.com\n- **Issues**: [GitHub Issues](https://github.com/altergom/go-agent/issues)\n\n---\n\n<p align=\"center\">\n  <strong>祝大家2026offer多多福满年❤️</strong><br>\n</p>\n"}, "c3a4907c12a9b53d853af903ee3b101cc41c458e": {"t": 1785766582.877395, "n": 3117, "h": "4037d7af8297f2ad", "c": "# Go-Agent\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/github/go-mod/go-version/cloudwego/eino?style=flat-square&logo=go\" alt=\"Go Version\">\n  <img src=\"https://img.shields.io/badge/Framework-Eino-blue?style=flat-square\" alt=\"Framework\">\n  <img src=\"https://img.shields.io/badge/License-Apache--2.0-green?style=flat-square\" alt=\"License\">\n</p>\n\nGo-Agent 是一个基于 [CloudWeGo-Eino](https://github.com/cloudwego/eino) 构建的高性能、工程化 AI Agent 实战项目。它不仅是一个演示 Demo，更是一套深度面向 **大模型工程化面试与生产实践** 的参考架构，旨在展示如何将 RAG、MCP、HITL 等前沿技术真正落地。\n\n\n---\n\n## 🌟 核心特性\n\n- 🚀 **意图驱动编排**：基于 Eino Graph (DAG) 实现复杂的意图识别与任务分发流。\n- 🔍 **全栈 RAG 系统**：集成从文档加载、切分、向量化到多路召回的完整检索增强生成链路。\n- 🤝 **人机协同 (HITL)**：深度实现“中断-审批-恢复”机制，支持复杂的 SQL 执行人工确认流程。\n- 🔌 **MCP 协议集成**：接入 Model Context Protocol (MCP)，实现 Agent 与外部数据库、工具的标准化交互。\n- 🔄 **自动 SFT 数据闭环**：无侵入式采集业务轨迹，利用“教师模型”自动标注，构建自我进化的模型微调语料库。\n- ⚡ **推理性能优化**：内置投机采样 (Speculative Sampling) 及 TTFT (首字延迟) 优化策略，平衡成本、智力与响应速度。\n\n---\n\n## 🏗️ 系统架构\n\n项目采用组件化设计，将 AI 能力抽象为可插拔的节点，核心逻辑结构如下：\n\n*   **模型工厂层**：统一封装 Ark (豆包)、OpenAI、DeepSeek 等主流模型，支持配置化热切换。\n*   **编排层 (Eino Graph)**：利用有向无环图管理长链路对话、意图路由及工具调用。\n*   **数据工厂层**：通过 Callbacks 拦截器实现自动化的数据采集与“间接蒸馏”标注。\n\n---\n\n## 📂 项目结构\n\n```bash\n├── api/            # 接入层：RESTful 路由、Session 管理及 HITL 逻辑处理\n├── flow/           # 编排层：核心业务逻辑图 (Intention, SQL, Chat) 的构建\n├── model/          # 抽象层：多厂商 ChatModel 与 EmbeddingModel 工厂实现\n├── rag/            # 核心层：RAG 完整组件与编排流 (Index & Retriever)\n├── SQL/            # 工具层：MCP 工具集成与 SQL 生成、执行逻辑\n├── tool/           # 工程化：SFT 采集标注、投机采样、推理加速组件\n├── config/         # 配置层：全局单例与环境变量加载\n└── main.go         # 入口：服务启动与组件初始化\n```\n\n---\n\n## 🚀 快速开始\n\n### 1. 环境配置\n克隆项目并配置环境变量：\n\n```bash\ngit clone https://github.com/your-repo/go-agent.git\ncd go-agent\ncp .env.example .env\n```\n\n### 2. 基础组件准备 (RAG 依赖)\n本项目 RAG 部分依赖 Milvus (向量数据库) 和 Elasticsearch (全文搜索)，推荐使用 Docker 快速部署：\n\n#### Elasticsearch 安装\n```bash\ndocker run -d --name elasticsearch \\\n  -p 9200:9200 \\\n  -e \"discovery.type=single-node\" \\\n  -e \"ES_JAVA_OPTS=-Xms512m -Xmx512m\" \\\n  elasticsearch:7.17.9\n```\n\n#### Milvus 安装 (Standalone)\n```bash\n# 1. 下载 docker-compose 配置文件\nwget https://github.com/milvus-io/milvus/releases/download/v2.5.4/milvus-standalone-docker-compose.yml -O docker-compose.yml\n\n# 2. 启动服务\ndocker-compose up -d\n```\n*详细文档请参考：[Milvus 官方安装指南](https://milvus.io/docs/zh/install_standalone-docker-compose.md)*\n\n### 3. 填写配置\n在 `.env` 文件中配置您的模型服务商信息及基础组件地址：\n\n```env\n# 模型配置\nARK_KEY=your_ark_key\n# ... 其他厂商配置\n\n# Milvus 配置\nMILVUS_ADDR=localhost:19530\nMILVUS_COLLECTION_NAME=GoAgent\n\n# Elasticsearch 配置\nES_ADDRESS=http://localhost:9200\nES_INDEX=go_agent_docs\n```\n\n### 4. 启动服务\n```bash\ngo mod tidy\ngo run .\n```\n服务启动后，访问 `http://localhost:8080/final_graph.html` 体验完整功能。\n\n---\n\n## 📖 技术深潜 (面向面试与实战)\n\n本项目针对大模型工程化中的常见痛点提供了参考实现：\n\n1.  **Agent 如何解决一致性？**：通过 Eino 的状态管理与类型检查。\n2.  **如何处理长文本检索的精度？**：通过混合路由与重写 (Rewriter) 机制。\n3.  **如何低成本提升模型能力？**：通过本项目内置的 SFT 自动闭环采集业务数据。\n4.  **如何优化高并发下的响应体验？**：通过投机采样模拟应用层加速。\n\n---\n\n## 📜 许可证\n\n本项目基于 [Apache-2.0](./LICENSE) 协议开源。\n\n---\n\n## 🤝 联系与贡献\n\n*   **提交 Issue**：欢迎提交 Bug 或 Feature Request。\n*   **联系作者**：`kele3325@gmail.com`您的建议对本项目非常重要。\n\n---\n<p align=\"center\">Built with ❤️ by the Go-Agent Community</p>\n"}, "08f366c9a8e65e0467b52042723f4b96739ff582": {"t": 1785766584.1414912, "n": 1587, "h": "3a1a22b30b15f114", "c": "# Go-Agent: 大模型工程化实践与教学项目\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/cloudwego/eino)](https://go.dev/)\n[![Framework](https://img.shields.io/badge/Framework-Eino-blue)](https://github.com/cloudwego/eino)\n\n## 📌 项目定位\n\n本项目不仅是一个基于 **CloudWeGo-Eino** 构建的 AI Agent 示例，更是一份深度面向**大模型工程化面试与实战**的教学指南。我们旨在通过具体的代码实现，向开发者展示如何将 RAG、MCP、HITL等前沿技术落地于生产环境。\n\n---\n\n## 🏗️ 核心架构设计\n\n项目采用组件化设计，严格遵循 Eino 的编排理念，将 AI 能力抽象为可插拔的节点：\n\n### 1. 模型层 (Model & Embedding)\n\n* **多模型工厂**: 统一封装了 Ark (豆包)、OpenAI、Qwen、DeepSeek 等主流模型。\n* **配置驱动**: 通过环境变量实现模型热切换。\n\n### 2. 闭环 SFT 系统 (Self-Evolution Loop)\n\n这是本项目的核心亮点，实现了一套“自我进化”的数据工厂：\n\n* **自动采集**: 通过 Eino Callbacks 机制，无侵入式拦截 ChatModel 的输入输出。\n* **自动标注**: 引入“教师模型”对原始响应进行打分和修正，实现间接蒸馏。\n\n### 3. 推理加速组件 (Inference Optimization)\n\n* **投机采样 (Speculative Sampling)**: 模拟应用层投机采样逻辑，利用“学生模型”抢跑，“教师模型”核验。\n* **TTFT 优化**: 侧重于首字响应延迟优化，通过流式差异化更新提升用户感知速度。\n\n---\n\n## 📂 目录结构说明\n\n```bash\n├── api/            # 接入层：RESTful 路由与业务逻辑转换\n├── config/         # 配置层：环境变量加载与全局单例管理\n├── model/          # 抽象层：ChatModel 与 EmbeddingModel 的工厂实现\n│   ├── chat_model/ # 支持多厂商注册与按需实例化\n├── rag/            # 核心层：检索增强生成（RAG）的完整编排\n│   ├── tools/      # RAG 原子组件：Loader, Splitter, Indexer, Retriever\n│   ├── compose/    # 编排逻辑：Graph 有向无环图的构建\n├── tool/           # 工具层：SFT 采集、标注、投机采样逻辑\n│   ├── sft/        # 包含自动标注器、存储管理与导出工具\n├── main.go         # 入口：全局组件初始化与 Web 服务启动\n```\n\n---\n\n## 🚀 快速开始\n\n请参考 `.env.example` 配置你的 API Key，然后运行：\n\n```bash\ngo run .\n```\n\n---\n\n## 🎓 教学目标\n\n我们希望通过本项目，让你掌握：\n\n1. 如何设计一个高可扩展的模型工厂。\n2. 如何利用 Eino 的 **Graph (DAG)** 编排复杂的多节点逻辑。\n3. 如何构建自动化数据闭环，为模型微调积累高质量语料。\n4. 如何在业务层实现推理加速策略，平衡成本、智力与速度。\n"}, "ff8051f582868a1b0904f14f5e65f0445d346e41": {"t": 1785766585.3351574, "n": 1538, "h": "868b64ba18724cd1", "c": "# go-agent\n\n基于 Eino 构建的数据分析/处理智能体示例项目，目标是尽可能覆盖常见 LLM 技术栈，作为入门与实践参考。\n\n当前实现重点在 RAG 方向，后续计划扩展 Multi-Agent 与 HITL。\n\n## 功能特性\n\n- 基础对话与流式对话接口\n- RAG 文档入库与召回答复\n- Milvus 向量数据库集成\n- 简单的前端/HTML 测试页面\n- 支持 Ark / OpenAI ChatModel（Embedding 当前使用 Ark）\n\n## 目录结构\n\n- `api/`：HTTP 接口与路由\n- `config/`：配置与环境变量加载\n- `model/`：聊天模型封装\n- `rag/`：RAG 相关工具与编排\n- `tool/`：通用工具函数\n- `front/`：前端相关（预留/实验）\n- `template/`：模板资源（预留/实验）\n- `*.html`：本地测试页面\n\n## 快速开始\n\n### 1) 环境准备\n\n- Go 1.20+（建议）\n- Milvus（本地或 Docker）\n\nMilvus 启动参考：`rag/README.md`\n\n### 2) 配置环境变量\n\n在项目根目录创建 `.env`，示例：\n\n```env\n# 模型类型（ChatModel 支持 ark/openai）\nCHAT_MODEL_TYPE=ark\nEMBEDDING_MODEL_TYPE=ark\n\n# Ark 配置\nARK_KEY=your_api_key\nARK_CHAT_MODEL=your_chat_model\nARK_EMBEDDING_MODEL=your_embedding_model\n\n# OpenAI 配置（当 CHAT_MODEL_TYPE=openai 时生效）\nOPENAI_KEY=your_api_key\nOPENAI_CHAT_MODEL=gpt-4\n\n# Milvus 配置\nMILVUS_ADDR=localhost:27017\nMILVUS_USERNAME=\nMILVUS_PASSWORD=\nMILVUS_COLLECTION=eino_collection\nSIMILARITY_THRESHOLD=\nMILVUS_TOPK=10\n```\n\n### 3) 启动服务\n\n```bash\ngo run .\n```\n\n服务默认监听 `:8080`。\n\n## 测试页面\n\n该页面在分支：`retrieve-fix`生效\n\n启动后可直接访问\n\n- `http://localhost:8080/chat_test.html`：基础对话测试\n- `http://localhost:8080/rag_index.html`：RAG 文档入库\n- `http://localhost:8080/rag_ask.html`：RAG 召回答复\n\n根路径 `/` 会自动跳转到可用的测试页面。\n\n## API 简要说明\n\n- `POST /api/chat/test`：常规对话\n- `POST /api/chat/test/stream`：流式对话\n- `POST /api/document/insert`：文档入库\n- `POST /api/rag/ask`：RAG 问答\n- `GET /api/milvus/collections`：列出集合\n- `DELETE /api/milvus/collections/:name`：删除集合\n\nRAG 说明\n\nRAG 构建、Milvus 启动与相关说明见 `rag/README.md`。\n\n## 许可\n\n本项目采用 `LICENSE` 中声明的开源协议。\n"}, "65aa2b4b1471eddc4087e8805a50e2895714ad16": {"t": 1785766586.825964, "n": 55, "h": "35ebd95942bb9576", "c": "# go-agent\n基于Eino实现数据分析处理智能体，目标尽可能的综合常见llm技术使该项目成为入门教程\n"}}}}