diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index a3b14fe6a..000000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,267 +0,0 @@ -# WeKnora 开发环境快速入门 - -> 无需重新构建 Docker 镜像，实现秒级代码热更新！ - -## 🚀 快速开始（3 种方式） - -### 方式 1：推荐 - 使用 Make 命令 - -**终端 1** - 启动基础设施： -```bash -make dev-start -``` - -**终端 2** - 启动后端： -```bash -make dev-app -``` - -**终端 3** - 启动前端： -```bash -make dev-frontend -``` - -访问 http://localhost:5173 开始开发！ - -### 方式 2：使用脚本命令 - -```bash -# 终端 1 -./scripts/dev.sh start - -# 终端 2 -./scripts/dev.sh app - -# 终端 3 -./scripts/dev.sh frontend -``` - -### 方式 3：一键启动（交互式） - -```bash -./scripts/quick-dev.sh -``` - -按照提示选择是否启动后端和前端。 - -## 📋 常用命令 - -| 命令 | 说明 | -|------|------| -| `make dev-start` | 启动基础设施（postgres, redis, minio 等） | -| `make dev-stop` | 停止所有服务 | -| `make dev-restart` | 重启所有服务 | -| `make dev-status` | 查看服务状态 | -| `make dev-logs` | 查看服务日志 | -| `make dev-app` | 启动后端（需先启动基础设施） | -| `make dev-frontend` | 启动前端（需先启动基础设施） | - -## 🎯 访问地址 - -| 服务 | 地址 | -|------|------| -| 前端开发服务器 | http://localhost:5173 | -| 后端 API | http://localhost:8080 | -| PostgreSQL | localhost:5432 | -| Redis | localhost:6379 | -| MinIO Console | http://localhost:9001 | -| Neo4j Browser | http://localhost:7474 | -| Jaeger UI | http://localhost:16686 | - -## 💡 开发工作流对比 - -### ❌ 旧方式（慢） - -```bash -# 每次修改代码后 -sh scripts/build_images.sh -p # 重新构建镜像（2-5分钟） -sh scripts/start_all.sh --no-pull # 重启容器 -``` - -### ✅ 新方式（快） - -```bash -# 首次启动（只需一次） -make dev-start - -# 修改后端代码 -# → Ctrl+C 停止 → make dev-app 重启（5-10秒） - -# 修改前端代码 -# → 自动热重载（无需任何操作） -``` - -**时间对比**： -- 旧方式：每次修改 2-5 分钟 -- 新方式首次：1-2 分钟 -- 新方式后续： - - 后端修改：5-10 秒 - - 前端修改：实时热重载 - -## 🔥 进阶：后端热重载 - -安装 Air 实现后端代码修改后自动重启： - -```bash -# 安装 Air -go install github.com/cosmtrek/air@latest - -# 确保 $GOPATH/bin 在 PATH 中 -export PATH=$PATH:$(go env GOPATH)/bin - -# 使用 Air 启动（自动检测） -make dev-app -# 或直接运行 -air -``` - -修改 Go 代码后，Air 会自动重新编译和重启，无需手动操作！ - -## 📝 开发场景示例 - -### 场景 1：只修改前端 - -```bash -# 一次性启动基础设施 -make dev-start - -# 启动前端，修改代码自动热重载 -make dev-frontend -``` - -### 场景 2：只修改后端 - -```bash -# 启动基础设施 -make dev-start - -# 启动后端（如果安装了 Air，支持热重载） -make dev-app -``` - -### 场景 3：同时开发前后端 - -```bash -# 终端 1：启动基础设施 -make dev-start - -# 终端 2：启动后端 -make dev-app - -# 终端 3：启动前端 -make dev-frontend -``` - -## 🛠 VS Code 调试配置 - -创建 `.vscode/launch.json`： - -```json -{ - "version": "0.2.0", - "configurations": [ - { - "name": "Launch WeKnora Server", - "type": "go", - "request": "launch", - "mode": "auto", - "program": "${workspaceFolder}/cmd/server", - "env": { - "DB_HOST": "localhost", - "DB_PORT": "5432", - "DOCREADER_ADDR": "localhost:50051", - "MINIO_ENDPOINT": "localhost:9000", - "REDIS_ADDR": "localhost:6379", - "OTEL_EXPORTER_OTLP_ENDPOINT": "localhost:4317", - "NEO4J_URI": "bolt://localhost:7687" - } - } - ] -} -``` - -然后按 F5 开始调试！ - -## 🐛 故障排除 - -### 问题：启动后端时报错连接不到数据库 - -**解决**：确保先运行了 `make dev-start` 并等待 30 秒让服务完全启动。 - -查看服务状态： -```bash -make dev-status -``` - -### 问题：前端访问 API 时报 CORS 错误 - -**解决**：前端已配置代理，确保： -1. 后端运行在 `localhost:8080` -2. 前端运行在 `localhost:5173` -3. 查看 `frontend/vite.config.ts` 的代理配置 - -### 问题：端口被占用 - -**解决**：修改 `.env` 文件中的端口配置： - -```bash -# .env -DB_PORT=5433 # 默认 5432 -REDIS_PORT=6380 # 默认 6379 -MINIO_PORT=9001 # 默认 9000 -``` - -然后重启服务： -```bash -make dev-restart -``` - -### 问题：DocReader 需要重新构建 - -**解决**：DocReader 仍使用 Docker 镜像，需要重新构建： - -```bash -sh scripts/build_images.sh -d -make dev-restart -``` - -## 🎯 生产环境部署 - -开发完成后需要部署时： - -```bash -# 构建所有镜像 -sh scripts/build_images.sh - -# 或只构建特定镜像 -sh scripts/build_images.sh -p # 后端 -sh scripts/build_images.sh -f # 前端 -sh scripts/build_images.sh -d # DocReader - -# 启动生产环境 -sh scripts/start_all.sh -``` - -## 📚 更多文档 - -- [完整开发指南](docs/开发指南.md) -- [API 文档](docs/API.md) -- [Agent 开发](docs/AGENT.md) - -## 💪 最佳实践 - -1. **日常开发**：使用 `make dev-*` 命令，享受快速迭代 -2. **提交前测试**：使用完整 Docker 环境测试集成功能 -3. **生产部署**：使用构建镜像的方式部署 - -## 🎉 总结 - -使用开发模式，你可以： - -✅ **不重新构建镜像** - 直接在本地运行代码 -✅ **秒级热更新** - 前端自动热重载，后端快速重启 -✅ **完整调试支持** - IDE 断点调试，实时查看变量 -✅ **节省时间** - 每次修改从 2-5 分钟降至 5-10 秒 - -祝你开发愉快！🚀 - diff --git a/docs/AGENT.md b/docs/AGENT.md deleted file mode 100644 index 8ec12f9b3..000000000 --- a/docs/AGENT.md +++ /dev/null @@ -1,527 +0,0 @@ -# WeKnora Agent Mode 文档 - -## 概述 - -WeKnora Agent Mode 是基于 ReAct (Reasoning + Acting) 框架实现的智能代理系统，能够通过工具调用和迭代推理来回答复杂问题。 - -### 核心特性 - -- **ReAct 框架**: Thought → Action → Observation 循环 -- **工具系统**: 7个知识库相关工具 -- **可选规划**: 可在执行前生成任务计划 -- **事件追踪**: 完整的执行过程可视化 -- **灵活配置**: 支持多种参数调整 - -## 架构设计 - -### Agent 工作流程 - -``` -用户查询 - ↓ -[可选] 生成执行计划 - ↓ -┌─────────────────┐ -│ ReAct 循环开始 │ -├─────────────────┤ -│ 1. Think (思考) │ → LLM 分析当前状态 -│ 2. Act (行动) │ → 调用工具获取信息 -│ 3. Observe (观察)│ → 处理工具返回结果 -│ [可选] Reflect │ → 反思当前步骤 -│ 4. Decide (决策)│ → 继续或结束? -└─────────────────┘ - ↓ -生成最终答案 -``` - -### 组件结构 - -``` -internal/agent/ -├── engine.go # Agent 执行引擎 -├── prompts.go # System prompts -└── tools/ # 工具系统 - ├── tool.go - ├── registry.go - ├── knowledge_search.go - ├── multi_kb_search.go - ├── list_knowledge_bases.go - ├── get_chunk_detail.go - ├── get_related_chunks.go - ├── query_knowledge_graph.go - └── get_document_info.go -``` - -## 配置说明 - -### Agent 配置结构 - -```go -type AgentConfig struct { - Enabled bool // 是否启用 Agent 模式 - EnablePlanning bool // 是否先规划 - MaxIterations int // 最大迭代次数 (1-20) - ReflectionEnabled bool // 是否启用反思 - AllowedTools []string // 允许的工具列表 - Temperature float64 // LLM 温度 (0-2) - ThinkingModelID string // 推理模型 ID - KnowledgeBases []string // 可访问的知识库 ID -} -``` - -### 全局配置 (config.yaml) - -```yaml -agent: - enabled: true - default_max_iterations: 5 - default_temperature: 0.7 - reflection_enabled: false - default_tools: - - knowledge_search - - multi_kb_search - - list_knowledge_bases - - get_chunk_detail - - get_related_chunks - - query_knowledge_graph - - get_document_info -``` - -## 可用工具 - -### 1. knowledge_search -搜索指定知识库中的相关内容。 - -**参数:** -- `knowledge_base_id` (必需): 知识库ID -- `query` (必需): 搜索查询内容 -- `top_k` (可选): 返回结果数量，默认5 - -**示例:** -``` -knowledge_search(knowledge_base_id="kb123", query="什么是RAG", top_k=5) -``` - -### 2. multi_kb_search -在多个知识库中智能搜索，自动选择最相关的知识库。 - -**参数:** -- `query` (必需): 搜索查询内容 -- `top_k` (可选): 每个知识库返回的结果数量，默认3 - -**适用场景:** 跨知识库查询，不确定信息在哪个知识库中 - -### 3. list_knowledge_bases -列出当前可访问的所有知识库。 - -**参数:** 无 - -**用途:** 了解有哪些知识库可以搜索 - -### 4. get_chunk_detail -获取指定chunk的详细信息，包括完整内容、来源文档。 - -**参数:** -- `chunk_id` (必需): Chunk ID - -**用途:** 当搜索结果不够详细时获取完整内容 - -### 5. get_related_chunks -获取与指定chunk相关的其他chunks。 - -**参数:** -- `chunk_id` (必需): Chunk ID -- `relation_type` (可选): "sequential" (顺序) 或 "semantic" (语义) -- `limit` (可选): 返回数量，默认5 - -**用途:** 发现相关信息，扩展上下文 - -### 6. query_knowledge_graph -查询知识图谱中的实体和关系。 - -**参数:** -- `knowledge_base_id` (必需): 知识库ID -- `query` (必需): 查询内容（实体名称或查询文本） - -**前提:** 知识库已配置知识图谱抽取 - -### 7. get_document_info -获取文档的元数据信息。 - -**参数:** -- `knowledge_id` (必需): 文档/知识ID - -**用途:** 了解文档的整体情况 - -## 使用指南 - -### 创建 Agent Session - -```bash -POST /api/v1/sessions - -{ - "knowledge_base_id": "kb123", - "session_strategy": { - "summary_model_id": "model123", - ... - }, - "agent_config": { - "enabled": true, - "enable_planning": false, - "max_iterations": 5, - "reflection_enabled": false, - "allowed_tools": [ - "knowledge_search", - "multi_kb_search", - "list_knowledge_bases" - ], - "temperature": 0.7, - "knowledge_bases": ["kb123", "kb456"] - } -} -``` - -### 发起 Agent 查询 - -```bash -POST /api/v1/sessions/{session_id}/agent-qa - -{ - "query": "请解释RAG技术的工作原理" -} -``` - -### 响应格式 - -Agent 会返回 SSE (Server-Sent Events) 流式响应： - -1. **知识引用** (可选) -```json -{ - "response_type": "references", - "knowledge_references": [...] -} -``` - -2. **Agent 思考过程** (可选，用于调试) -```json -{ - "response_type": "agent_thought", - "content": "我需要先搜索相关知识..." -} -``` - -3. **工具调用** (可选) -```json -{ - "response_type": "agent_action", - "content": "调用工具: knowledge_search" -} -``` - -4. **最终答案** -```json -{ - "response_type": "answer", - "content": "RAG技术的工作原理是...", - "done": true -} -``` - -## 最佳实践 - -### 1. 工具选择策略 - -- **已知知识库**: 使用 `knowledge_search` -- **不确定位置**: 使用 `multi_kb_search` -- **需要上下文**: 使用 `get_related_chunks` -- **探索阶段**: 先用 `list_knowledge_bases` - -### 2. 迭代次数设置 - -- **简单查询**: 3-5 次 -- **复杂问题**: 5-10 次 -- **探索性任务**: 10-15 次 -- **最大限制**: 20 次 (防止无限循环) - -### 3. 温度参数 - -- **精确查询**: 0.3-0.5 (更确定性) -- **创造性任务**: 0.7-1.0 (更多样性) -- **默认推荐**: 0.7 - -### 4. Planning 启用时机 - -- **复杂多步骤任务**: 启用 -- **简单直接查询**: 禁用 -- **探索性问题**: 启用 - -### 5. Reflection 启用时机 - -- **关键任务**: 启用 (提高准确性) -- **快速响应**: 禁用 (减少延迟) -- **默认**: 禁用 - -## 工作原理详解 - -### ReAct Prompt Template - -``` -你是一个智能知识库助手。你的任务是通过使用提供的工具来回答用户问题。 - -工作流程： -1. 分析用户问题，确定需要什么信息 -2. 使用合适的工具获取信息（可以多次调用不同工具） -3. 基于获取的信息，提供准确、完整的答案 - -注意事项： -- 优先使用 multi_kb_search 进行跨知识库搜索 -- 如果需要特定知识库，先用 list_knowledge_bases 查看可用知识库 -- 如果搜索结果不够详细，使用 get_chunk_detail 获取完整内容 -- 使用 get_related_chunks 发现相关信息 -- 如果涉及实体关系，使用 query_knowledge_graph -- 引用信息时，说明来源（chunk_id 或 knowledge_base） -- 如果找不到相关信息，诚实告知用户 - -当前可访问的知识库： -{knowledge_bases} - -{plan_context} -``` - -### 工具调用解析 - -Agent 会尝试从 LLM 输出中解析工具调用，支持的格式： - -``` -tool_name(arg1="value1", arg2="value2") -``` - -例如： -``` -knowledge_search(knowledge_base_id="kb123", query="RAG技术") -``` - -### 循环控制 - -Agent 会在以下情况停止： - -1. LLM 输出包含 "最终答案" 或 "Final Answer" -2. 达到最大迭代次数 -3. 工具调用失败且无法恢复 -4. 检测到重复循环模式 - -## 事件追踪 - -Agent 执行过程中会发送以下事件 (通过 Event Bus): - -### agent.plan -```go -type AgentPlanData struct { - Query string - Plan []string - Duration int64 -} -``` - -### agent.step -```go -type AgentStepData struct { - Iteration int - Thought string - ToolCalls []ToolCall - Duration int64 -} -``` - -### agent.tool -```go -type AgentActionData struct { - Iteration int - ToolName string - ToolInput map[string]interface{} - ToolOutput string - Success bool - Error string - Duration int64 -} -``` - -## 示例场景 - -### 场景 1: 简单知识查询 - -**用户问题**: "什么是 RAG?" - -**Agent 执行流程**: -1. **Think**: 需要搜索 RAG 相关知识 -2. **Act**: `multi_kb_search(query="RAG")` -3. **Observe**: 获得3条相关结果 -4. **Think**: 信息足够，可以回答 -5. **Final Answer**: 基于搜索结果生成答案 - -**迭代次数**: 2 - -### 场景 2: 跨文档关联查询 - -**用户问题**: "比较 RAG 和微调的优缺点" - -**Agent 执行流程**: -1. **Think**: 需要分别查找 RAG 和微调的信息 -2. **Act**: `multi_kb_search(query="RAG优缺点")` -3. **Observe**: 获得 RAG 相关信息 -4. **Think**: 还需要微调的信息 -5. **Act**: `multi_kb_search(query="模型微调优缺点")` -6. **Observe**: 获得微调相关信息 -7. **Think**: 信息完整，进行对比 -8. **Final Answer**: 综合两者信息生成对比答案 - -**迭代次数**: 4 - -### 场景 3: 深入探索 - -**用户问题**: "详细解释向量数据库的工作原理" - -**Agent 执行流程**: -1. **Think**: 先查看有哪些知识库 -2. **Act**: `list_knowledge_bases()` -3. **Observe**: 发现有"数据库技术"知识库 -4. **Think**: 在该知识库中搜索 -5. **Act**: `knowledge_search(knowledge_base_id="db_kb", query="向量数据库")` -6. **Observe**: 找到相关 chunk -7. **Think**: 需要更多细节 -8. **Act**: `get_chunk_detail(chunk_id="chunk123")` -9. **Observe**: 获得完整内容 -10. **Think**: 查看相关内容 -11. **Act**: `get_related_chunks(chunk_id="chunk123", relation_type="sequential")` -12. **Observe**: 获得上下文 -13. **Final Answer**: 基于详细信息生成深入解释 - -**迭代次数**: 7 - -## 常见问题 - -### Q: Agent 和普通 RAG 有什么区别？ - -**A**: -- **普通 RAG**: 一次性检索 → 生成答案 -- **Agent**: 可以多次迭代，根据中间结果调整策略，调用不同工具 - -### Q: 什么时候使用 Agent 模式？ - -**A**: -- 需要多步推理的复杂问题 -- 需要在多个知识库中查找信息 -- 需要深入探索和关联分析 -- 问题模糊，需要澄清和逐步细化 - -### Q: Agent 模式的成本如何？ - -**A**: -- **Token 消耗**: 比普通 RAG 高 (多次 LLM 调用) -- **响应时间**: 较长 (迭代执行) -- **准确性**: 通常更高 (多步验证) - -### Q: 如何优化 Agent 性能？ - -**A**: -1. 合理设置 `max_iterations` (避免过多) -2. 选择必要的工具 (`allowed_tools`) -3. 禁用不需要的功能 (planning, reflection) -4. 使用更快的模型作为 thinking_model - -### Q: 工具调用失败怎么办？ - -**A**: Agent 会： -1. 在 Observation 中记录错误 -2. 尝试使用其他工具 -3. 如果多次失败，会在最终答案中说明 - -## 技术限制与注意事项 - -### 当前限制 - -1. **工具调用解析**: 使用简单的模式匹配，可能无法处理复杂格式 -2. **Function Calling**: 当前使用 prompt-based 方式，未来可升级为原生 function calling -3. **并行工具调用**: 当前不支持，工具按顺序执行 -4. **图谱查询**: 当前使用 hybrid search，完整图谱功能开发中 - -### 未来改进 - -- [ ] 支持 LLM 原生 function calling (GPT-4, Claude 等) -- [ ] 并行工具执行 -- [ ] 更智能的循环检测 -- [ ] 工具结果缓存 -- [ ] 自定义工具注册 -- [ ] Agent 执行可视化 UI - -## 开发指南 - -### 创建自定义工具 - -```go -package tools - -import ( - "context" - "github.com/Tencent/WeKnora/internal/types" -) - -type CustomTool struct { - BaseTool - // 添加依赖 -} - -func NewCustomTool() *CustomTool { - return &CustomTool{ - BaseTool: NewBaseTool( - "custom_tool", - "工具描述", - ), - } -} - -func (t *CustomTool) Parameters() map[string]interface{} { - return map[string]interface{}{ - "type": "object", - "properties": map[string]interface{}{ - "param1": map[string]interface{}{ - "type": "string", - "description": "参数描述", - }, - }, - "required": []string{"param1"}, - } -} - -func (t *CustomTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { - // 实现工具逻辑 - param1 := args["param1"].(string) - - // 执行操作 - result := doSomething(param1) - - return &types.ToolResult{ - Success: true, - Output: result, - Data: map[string]interface{}{}, - }, nil -} -``` - -### 注册自定义工具 - -在 `agent_service.go` 的 `registerTools` 方法中添加： - -```go -case "custom_tool": - registry.RegisterTool(tools.NewCustomTool()) -``` - -## 总结 - -WeKnora Agent Mode 提供了强大的迭代推理能力，适用于复杂的知识查询场景。通过合理配置和工具选择，可以在准确性和效率之间找到最佳平衡点。 - -如有问题或建议，请提交 Issue 或 Pull Request。 - diff --git a/docs/CONTEXT_MANAGER.md b/docs/CONTEXT_MANAGER.md deleted file mode 100644 index 7e5bc4771..000000000 --- a/docs/CONTEXT_MANAGER.md +++ /dev/null @@ -1,401 +0,0 @@ -# LLM Context Manager - 大模型上下文管理器 - -## 概述 - -LLM Context Manager 是一个专门用于管理大模型对话上下文的组件，它**独立于消息存储系统**，专注于管理发送给大模型的上下文窗口。 - -### 关键特性 - -1. **独立管理**: 与消息的数据库存储分离，专门管理发送给 LLM 的上下文 -2. **Token 限制管理**: 自动监控和管理上下文的 Token 数量 -3. **智能压缩**: 当上下文超出限制时，自动应用压缩策略 -4. **按 Session 维护**: 每个会话独立管理其上下文 -5. **灵活配置**: 支持会话级别的自定义配置 - -## 为什么需要 Context Manager？ - -### 问题背景 - -- **消息存储** vs **LLM 上下文**: - - 消息存储：完整保存所有对话历史，用于展示和审计 - - LLM 上下文：有 Token 限制，需要精简管理 - -- **Token 限制**: 不同模型有不同的上下文窗口限制（如 4K, 8K, 16K tokens） - -- **性能优化**: 过长的上下文会增加推理时间和成本 - -### 解决方案 - -Context Manager 提供： -- 自动管理上下文窗口大小 -- 智能压缩历史消息 -- 保留最重要的上下文信息 -- 与消息存储解耦 - -## 架构设计 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Session Service │ -│ │ -│ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ Message Repo │ │ Context Manager │ │ -│ │ (Complete │ │ (LLM Context │ │ -│ │ History) │ │ Window) │ │ -│ └──────────────────┘ └──────────────────┘ │ -│ │ │ │ -│ │ Save all messages │ Manage LLM │ -│ │ for display │ context │ -│ ▼ ▼ │ -│ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ Database │ │ In-Memory │ │ -│ │ (Persistent) │ │ (Session-based) │ │ -│ └──────────────────┘ └──────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` - -## 压缩策略 - -### 1. 滑动窗口策略 (Sliding Window) - -保留最近的 N 条消息，丢弃更早的消息。 - -**优点:** -- 简单高效 -- 不需要额外的 LLM 调用 -- 适合短期对话 - -**配置示例:** -```json -{ - "enabled": true, - "max_tokens": 8192, - "compression_strategy": "sliding_window", - "recent_message_count": 20 -} -``` - -**工作原理:** -``` -原始消息: [system, msg1, msg2, msg3, ..., msg18, msg19, msg20, msg21, msg22] - ↑ - 保留最近20条消息 -压缩结果: [system, msg3, msg4, ..., msg20, msg21, msg22] - └─────┘ └──────────────────────────────────┘ - 保留系统消息 保留最近的20条消息 -``` - -### 2. 智能压缩策略 (Smart Compression) - -使用 LLM 总结旧消息，保留最近消息的完整内容。 - -**优点:** -- 保留历史关键信息 -- 更好的上下文连贯性 -- 适合长期对话 - -**配置示例:** -```json -{ - "enabled": true, - "max_tokens": 8192, - "compression_strategy": "smart", - "recent_message_count": 10 -} -``` - -**工作原理:** -``` -原始消息: [system, msg1, msg2, ..., msg15, msg16, msg17, msg18, msg19, msg20] - └───────────────┘ └─────────────────────────────┘ - 旧消息（总结） 最近消息（保留） - -压缩结果: [system, summary, msg16, msg17, msg18, msg19, msg20] - └─────┘ └──────┘ └──────────────────────────────┘ - 系统消息 总结 保留最近的10条消息（完整） -``` - -## 使用方法 - -### 1. 默认配置 - -如果不设置 `context_config`，系统使用默认配置： -- 最大 Token: 8192 -- 策略: 滑动窗口 -- 保留消息数: 20 - -```go -// 不需要特别配置，自动使用默认设置 -session := &types.Session{ - TenantID: tenantID, - KnowledgeBaseID: kbID, - // context_config 为 nil，使用默认配置 -} -``` - -### 2. 自定义配置 - 滑动窗口 - -```go -session := &types.Session{ - TenantID: tenantID, - KnowledgeBaseID: kbID, - ContextConfig: &types.ContextConfig{ - Enabled: true, - MaxTokens: 16384, // GPT-4 的上下文窗口 - CompressionStrategy: types.ContextCompressionSlidingWindow, - RecentMessageCount: 30, // 保留最近30条消息 - }, -} -``` - -### 3. 自定义配置 - 智能压缩 - -```go -session := &types.Session{ - TenantID: tenantID, - KnowledgeBaseID: kbID, - SummaryModelID: "gpt-4", // 用于总结的模型 - ContextConfig: &types.ContextConfig{ - Enabled: true, - MaxTokens: 8192, - CompressionStrategy: types.ContextCompressionSmart, - RecentMessageCount: 15, // 保留最近15条完整消息 - }, -} -``` - -### 4. 通过 API 创建/更新会话 - -```bash -# 创建带上下文配置的会话 -curl -X POST http://localhost:8080/api/v1/sessions \ - -H "Content-Type: application/json" \ - -H "X-Tenant-ID: 1" \ - -d '{ - "knowledge_base_id": "kb-123", - "context_config": { - "enabled": true, - "max_tokens": 8192, - "compression_strategy": "sliding_window", - "recent_message_count": 20 - } - }' -``` - -## 工作流程 - -### 对话流程 - -``` -1. 用户发送消息 - ↓ -2. 保存消息到数据库 (Message Repo) - ↓ -3. 添加消息到上下文管理器 (Context Manager) - ↓ -4. Context Manager 检查 Token 限制 - ↓ -5. 如果超出限制，应用压缩策略 - ↓ -6. 获取压缩后的上下文 - ↓ -7. 发送给 LLM - ↓ -8. 保存响应到数据库 - ↓ -9. 添加响应到上下文管理器 -``` - -### 代码示例 - -```go -// 在 AgentQA 中的使用 -func (s *sessionService) AgentQA(ctx context.Context, sessionID, query string, assistantMessageID string) ( - []*types.SearchResult, <-chan types.StreamResponse, error, -) { - // 1. 获取会话配置 - session, err := s.sessionRepo.Get(ctx, tenantID, sessionID) - - // 2. 从上下文管理器获取 LLM 上下文（自动应用压缩） - history, err := s.getContextForSession(ctx, session, sessionID) - // history 是压缩后的，适合发送给 LLM 的消息列表 - - // 3. 执行 Agent - eventChan, err := engine.ExecuteStreamWithHistory(ctx, query, history) - - // 4. 保存新消息后，添加到上下文管理器 - // s.AddMessageToContext(ctx, session, sessionID, newMessage) - - return searchResults, responseChan, nil -} -``` - -## 配置参数说明 - -### ContextConfig 字段 - -| 字段 | 类型 | 说明 | 默认值 | -|------|------|------|--------| -| `enabled` | bool | 是否启用上下文管理 | true | -| `max_tokens` | int | 最大 Token 数 | 8192 | -| `compression_strategy` | string | 压缩策略: "sliding_window" 或 "smart" | "sliding_window" | -| `recent_message_count` | int | 保留的最近消息数 | 20 (sliding_window)
10 (smart) | - -### 推荐配置 - -#### 短期对话（客服、问答） -```json -{ - "enabled": true, - "max_tokens": 4096, - "compression_strategy": "sliding_window", - "recent_message_count": 15 -} -``` - -#### 长期对话（咨询、助手） -```json -{ - "enabled": true, - "max_tokens": 8192, - "compression_strategy": "smart", - "recent_message_count": 10 -} -``` - -#### 高端模型（GPT-4 Turbo, Claude） -```json -{ - "enabled": true, - "max_tokens": 16384, - "compression_strategy": "smart", - "recent_message_count": 20 -} -``` - -## 监控和调试 - -### 查看上下文统计 - -```go -// 获取上下文统计信息 -stats, err := contextManager.GetContextStats(ctx, sessionID) -if err == nil { - log.Printf("Session %s context stats:", sessionID) - log.Printf(" Messages: %d", stats.MessageCount) - log.Printf(" Tokens: ~%d", stats.TokenCount) - log.Printf(" Compressed: %v", stats.IsCompressed) - log.Printf(" Original messages: %d", stats.OriginalMessageCount) -} -``` - -### 日志示例 - -``` -INFO Using custom context config for session abc123: strategy=smart, max_tokens=8192, recent_count=10 -INFO Context exceeds max tokens (9500 > 8192), applying compression -INFO Summarizing 15 old messages -INFO Successfully summarized 15 messages -INFO Smart compression: 25 -> 11 messages (system: 1, compressed: 1, recent: 10) -INFO LLM context stats for session abc123: messages=11, tokens=~7800, compressed=true -``` - -## 与消息存储的区别 - -| 特性 | 消息存储 (Message Repo) | 上下文管理器 (Context Manager) | -|------|------------------------|------------------------------| -| 目的 | 完整保存对话历史 | 管理 LLM 输入上下文 | -| 存储 | 数据库（持久化） | 内存（会话级别） | -| 内容 | 所有消息（完整） | 压缩后的消息 | -| 大小限制 | 无限制 | 受 Token 限制 | -| 使用场景 | 展示历史、审计 | LLM 推理输入 | -| 生命周期 | 永久保存 | 会话期间 | - -## 最佳实践 - -1. **选择合适的策略**: - - 短对话 → 滑动窗口（性能更好） - - 长对话 → 智能压缩（保留更多上下文） - -2. **配置 Token 限制**: - - 设置为模型上下文窗口的 70-80% - - 为响应留出足够空间 - -3. **调整保留消息数**: - - 滑动窗口: 15-30 条消息 - - 智能压缩: 8-15 条最近消息 - -4. **监控压缩效果**: - - 定期检查 Token 使用情况 - - 观察压缩是否影响对话质量 - -5. **性能考虑**: - - 智能压缩会额外调用 LLM（有成本） - - 滑动窗口无额外开销 - -## 数据库迁移 - -运行以下迁移脚本添加 `context_config` 字段： - -### MySQL -```bash -mysql -u root -p your_database < migrations/mysql/06-add-context-config-to-sessions.sql -``` - -### ParadeDB/PostgreSQL -```bash -psql -U postgres -d your_database -f migrations/paradedb/06-add-context-config-to-sessions.sql -``` - -## 常见问题 - -### Q1: 上下文管理器的数据会持久化吗？ -**A**: 不会。上下文管理器是内存级别的，按 Session 维护。重启后会清空，需要从消息历史重新构建。 - -### Q2: 如何清空某个会话的上下文？ -**A**: -```go -err := contextManager.ClearContext(ctx, sessionID) -``` - -### Q3: 压缩后的消息会影响数据库中的消息吗？ -**A**: 不会。压缩只影响发送给 LLM 的上下文，数据库中的消息完整保留。 - -### Q4: 智能压缩的总结质量如何保证？ -**A**: -- 使用会话配置的 `summary_model_id` 模型 -- 可以使用更强的模型（如 GPT-4）进行总结 -- 总结时使用低 temperature (0.3) 确保一致性 - -### Q5: 如何为现有会话启用上下文管理？ -**A**: -```bash -# 更新会话配置 -curl -X PUT http://localhost:8080/api/v1/sessions/{session_id} \ - -H "Content-Type: application/json" \ - -H "X-Tenant-ID: 1" \ - -d '{ - "context_config": { - "enabled": true, - "max_tokens": 8192, - "compression_strategy": "sliding_window", - "recent_message_count": 20 - } - }' -``` - -## 未来改进 - -- [ ] 支持更多压缩策略（如 MapReduce 总结） -- [ ] 支持自定义 Token 计算器 -- [ ] 持久化压缩后的上下文摘要 -- [ ] 支持跨会话的上下文共享 -- [ ] 添加更详细的压缩指标和监控 -- [ ] 支持上下文恢复机制 - -## 参考 - -- [Agent 文档](./AGENT.md) -- [API 文档](./API.md) -- [消息管理](../internal/types/message.go) - diff --git a/docs/MCP功能使用说明.md b/docs/MCP功能使用说明.md new file mode 100644 index 000000000..a43604865 --- /dev/null +++ b/docs/MCP功能使用说明.md @@ -0,0 +1,30 @@ +## MCP 功能使用说明 + +### 功能概述 +- MCP（Model Context Protocol）让 WeKnora 可以安全地连接外部工具或数据源，扩展 Agent 在推理时可调用的能力。 +- 在前端 `设置 > MCP 服务`（`frontend/src/views/settings/McpSettings.vue`）中集中管理所有服务，无需手动改配置文件。 +- 每个服务都包含名称、传输方式（SSE / HTTP Streamable / Stdio）、连接地址或命令、认证信息以及高级超时与重试策略。 + +### 入口与界面 +- 打开控制台左侧菜单 `设置 -> MCP 服务`，即可看到当前租户下的所有 MCP 服务列表。 +- 列表中可快速启停服务、查看描述，并通过右侧菜单执行“测试 / 编辑 / 删除”。 +- “添加服务”按钮会弹出 `McpServiceDialog`，用于创建或修改服务。 + +### 常用操作流程 +1. **新建服务** + - 点击“添加服务”，填写名称与描述，选择传输方式。 + - SSE / HTTP Streamable 需提供可访问的服务 URL；Stdio 需配置 `uvx`/`npx` 命令与参数，可附加环境变量。 + - 根据需要填写 API Key、Bearer Token、超时与重试策略，保存后服务会出现在列表中。 +2. **启停服务** + - 在列表开关中切换启用状态，系统会即时调用后端 `updateMCPService`，失败时会自动回滚状态并弹出提示。 +3. **连接测试** + - 通过更多菜单选择“测试”，前端会调用 `/api/v1/mcp-services/{id}/test` 并弹出 `McpTestResult`。 + - 成功时会展示服务可用的工具清单（含输入 schema）和资源列表；失败时会显示错误信息，方便排查网络或鉴权问题。 +4. **编辑 / 删除** + - “编辑”会带出原有配置，修改后保存即可。 + - “删除”需要在弹窗中确认，完成后列表自动刷新。 + +### 使用建议 +- **传输方式选择**：优先使用 SSE 获取流式体验；需要标准 HTTP Streamable 兼容时再切换；本地调试或离线环境适合使用 Stdio 并在同机启动 MCP Server。 +- **鉴权管理**：将 API Key / Token 保存在“认证配置”中，生产环境建议单独创建最小权限 Key，并定期轮换。 +- **重试策略**：对公网或第三方服务适当提高 `retry_count` 与 `retry_delay`，避免间歇性超时导致 Agent 中断 \ No newline at end of file diff --git a/docs/快速开发模式说明.md b/docs/快速开发模式说明.md index 68b61efc8..70a4f03cc 100644 --- a/docs/快速开发模式说明.md +++ b/docs/快速开发模式说明.md @@ -1,74 +1,7 @@ # 快速开发模式说明 -## 🎯 问题背景 +解决开发流程中，每次修改 `app`（后端）或 `frontend`（前端）代码后，都需要打包Docker镜像的问题，实现这两个模块的热更新 -之前的开发流程中，每次修改 `app`（后端）或 `frontend`（前端）代码后，都需要： - -```bash -# 重新构建 Docker 镜像（耗时 2-5 分钟） -sh scripts/build_images.sh -p # 构建后端 -sh scripts/build_images.sh -f # 构建前端 - -# 重启容器 -sh scripts/start_all.sh --no-pull -``` - -这个流程非常耗时，严重影响开发效率。 - -## ✨ 解决方案 - -现在提供了**快速开发模式**，可以直接在本地运行应用和前端，只在 Docker 中启动基础设施服务（数据库、缓存等），实现： - -- ✅ **前端热重载**：修改代码自动刷新，无需重启 -- ✅ **后端快速重启**：修改代码后 5-10 秒即可重启 -- ✅ **无需构建镜像**：跳过耗时的镜像构建过程 -- ✅ **支持调试**：可以使用 IDE 断点调试 - -## 📦 新增文件 - -### 1. 核心配置文件 - -- **`docker-compose.dev.yml`** - 开发环境 Docker Compose 配置 - - 只启动基础设施服务（postgres, redis, minio, neo4j, docreader, jaeger） - - 不启动 app 和 frontend 容器 - -### 2. 开发脚本 - -- **`scripts/dev.sh`** - 开发环境管理脚本 - - 支持启动/停止基础设施 - - 支持本地运行 app 和 frontend - - 自动检测并使用 Air（Go 热重载工具） - -- **`scripts/quick-dev.sh`** - 一键启动开发环境脚本 - - 交互式启动所有服务 - - 自动创建日志目录 - -### 3. 配置文件 - -- **`.air.toml`** - Air 热重载配置 - - 监控 Go 文件变化 - - 自动重新编译和重启 - -- **`frontend/vite.config.ts`** - 更新的 Vite 配置 - - 添加 API 代理配置 - - 避免 CORS 问题 - -### 4. 文档 - -- **`DEVELOPMENT.md`** - 开发环境快速入门指南 -- **`docs/开发指南.md`** - 完整开发指南 -- **`docs/快速开发模式说明.md`** - 本文档 - -### 5. Makefile 更新 - -新增的 Make 命令： -- `make dev-start` - 启动开发环境基础设施 -- `make dev-stop` - 停止开发环境 -- `make dev-restart` - 重启开发环境 -- `make dev-logs` - 查看服务日志 -- `make dev-status` - 查看服务状态 -- `make dev-app` - 启动后端应用（本地） -- `make dev-frontend` - 启动前端（本地） ## 🚀 使用方法 @@ -104,28 +37,7 @@ make dev-frontend ./scripts/quick-dev.sh ``` -## 📊 效率对比 -### 旧方式（慢） - -| 操作 | 耗时 | -|------|------| -| 修改代码 | - | -| 重新构建镜像 | 2-5 分钟 | -| 重启容器 | 30-60 秒 | -| **总计** | **2.5-6 分钟** | - -### 新方式（快） - -| 操作 | 耗时 | -|------|------| -| 首次启动基础设施 | 1-2 分钟（仅一次） | -| **后续修改后端** | **5-10 秒** | -| **后续修改前端** | **实时热重载** | - -**效率提升：20-60 倍！** - -## 🎓 高级功能 ### 使用 Air 实现后端热重载 @@ -142,32 +54,6 @@ export PATH=$PATH:$(go env GOPATH)/bin make dev-app ``` -### VS Code 调试配置 - -创建 `.vscode/launch.json`： - -```json -{ - "version": "0.2.0", - "configurations": [ - { - "name": "Launch WeKnora Server", - "type": "go", - "request": "launch", - "mode": "auto", - "program": "${workspaceFolder}/cmd/server", - "env": { - "DB_HOST": "localhost", - "DOCREADER_ADDR": "localhost:50051", - "MINIO_ENDPOINT": "localhost:9000", - "REDIS_ADDR": "localhost:6379", - "OTEL_EXPORTER_OTLP_ENDPOINT": "localhost:4317", - "NEO4J_URI": "bolt://localhost:7687" - } - } - ] -} -``` ## 🔄 架构说明 @@ -217,39 +103,4 @@ make dev-app │ └─────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘ -``` - -## 🎯 使用场景 - -### 日常开发 - -使用**开发模式**（`make dev-*`），享受快速迭代。 - -### 集成测试 - -使用**生产模式**（`make start-all`），测试完整环境。 - -### 生产部署 - -```bash -# 构建镜像 -make build-images - -# 启动服务 -make start-all -``` - -## 🔧 故障排除 - -详见 [DEVELOPMENT.md](../DEVELOPMENT.md) 的故障排除部分。 - -## 📚 相关文档 - -- [开发环境快速入门](../DEVELOPMENT.md) -- [完整开发指南](./开发指南.md) -- [API 文档](./API.md) - -## 💬 反馈与建议 - -如有问题或建议，请提交 [Issue](https://github.com/Tencent/WeKnora/issues)。 - +``` \ No newline at end of file diff --git a/frontend/src/api/system/index.ts b/frontend/src/api/system/index.ts index e4bcf7bfc..c58835595 100644 --- a/frontend/src/api/system/index.ts +++ b/frontend/src/api/system/index.ts @@ -43,6 +43,22 @@ export interface ConversationConfig { context_template: string temperature: number max_tokens: number + use_custom_system_prompt?: boolean + use_custom_context_template?: boolean + max_rounds: number + embedding_top_k: number + keyword_threshold: number + vector_threshold: number + rerank_top_k: number + rerank_threshold: number + enable_rewrite: boolean + fallback_strategy: string + fallback_response: string + fallback_prompt?: string + summary_model_id?: string + rerank_model_id?: string + rewrite_prompt_system?: string + rewrite_prompt_user?: string } export function getSystemInfo(): Promise<{ data: SystemInfo }> { diff --git a/frontend/src/components/UserMenu.vue b/frontend/src/components/UserMenu.vue index 74e028434..34aa60cb8 100644 --- a/frontend/src/components/UserMenu.vue +++ b/frontend/src/components/UserMenu.vue @@ -18,7 +18,7 @@
- {{ $t('settings.modelConfig') }} + {{ $t('settings.modelManagement') }}
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts index 692e584bd..409726e2c 100644 --- a/frontend/src/i18n/locales/en-US.ts +++ b/frontend/src/i18n/locales/en-US.ts @@ -152,8 +152,10 @@ export default { settings: { title: 'Settings', modelConfig: 'Model Settings', + modelManagement: 'Model Management', agentConfig: 'Agent Settings', conversationConfig: 'Conversation Settings', + conversationStrategy: 'Conversation Strategy', webSearchConfig: 'Web Search', mcpService: 'MCP Service', systemSettings: 'System Settings', @@ -833,8 +835,8 @@ export default { title: 'Model Configuration', description: 'Select appropriate AI models for the knowledge base', llmLabel: 'LLM Model', - llmDesc: 'Large language model used for conversations and Q&A', - llmPlaceholder: 'Select an LLM model', + llmDesc: 'Large language model used for summarization and abstract generation (optional)', + llmPlaceholder: 'Select an LLM model (optional)', embeddingLabel: 'Embedding Model', embeddingDesc: 'Embedding model used for text vectorization', embeddingPlaceholder: 'Select an embedding model', @@ -1368,18 +1370,107 @@ export default { } }, conversationSettings: { - description: 'Configure default behavior and parameters for conversation modes, including Prompt settings for Agent mode and normal mode', + description: 'Configure default behavior and parameters for conversation modes, including prompts for Agent and normal modes', agentMode: 'Agent Mode', normalMode: 'Normal Mode', + menus: { + modes: 'Mode Settings', + models: 'Model Mapping', + thresholds: 'Retrieval Thresholds', + advanced: 'Advanced Settings' + }, + models: { + description: 'Manage thinking/chat models and re-rank models for both Agent and normal modes', + chatGroupLabel: 'Thinking / Chat Models', + chatGroupDesc: 'Includes Agent reasoning/planning model and the default chat/summary model for normal mode', + chatModel: { + label: 'Default chat model (normal mode)', + desc: 'Used when a conversation does not specify its own model', + placeholder: 'Select default chat model' + }, + rerankModel: { + label: 'Default ReRank model (normal mode)', + desc: 'Used for re-ranking when a session does not override it', + placeholder: 'Select default rerank model' + }, + rerankGroupLabel: 'ReRank Models', + rerankGroupDesc: 'Includes Agent rerank model and the default rerank model for normal mode' + }, + thresholds: { + description: 'Tune retrieval and re-ranking thresholds to balance accuracy and performance' + }, + maxRounds: { + label: 'History Rounds', + desc: 'Number of rounds kept for context and query rewrite' + }, + embeddingTopK: { + label: 'Embedding TopK', + desc: 'Number of documents kept after vector retrieval' + }, + keywordThreshold: { + label: 'Keyword Threshold', + desc: 'Minimum score for keyword retrieval' + }, + vectorThreshold: { + label: 'Vector Threshold', + desc: 'Minimum similarity for vector retrieval' + }, + rerankTopK: { + label: 'ReRank TopK', + desc: 'Documents kept after re-ranking' + }, + rerankThreshold: { + label: 'ReRank Threshold', + desc: 'Minimum score required after re-ranking' + }, + enableRewrite: { + label: 'Enable Query Rewrite', + desc: 'Automatically rewrite multi-turn queries for better recall' + }, + fallbackStrategy: { + label: 'Fallback Strategy', + desc: 'How to respond when no relevant documents are found', + fixed: 'Fixed response', + model: 'Let the model continue answering' + }, + fallbackResponse: { + label: 'Fixed fallback response', + desc: 'Text returned when using the fixed fallback strategy' + }, + fallbackPrompt: { + label: 'Fallback Prompt', + desc: 'Prompt used when fallback strategy is “model”' + }, + advanced: { + description: 'Configure query rewrite, fallback strategy and other advanced settings' + }, + rewritePrompt: { + system: 'Rewrite System Prompt', + user: 'Rewrite User Prompt', + desc: 'System prompt used during query rewrite', + userDesc: 'User prompt used during query rewrite' + }, + chatModel: { + label: 'LLM Model', + desc: 'Large language model used for summarization and abstract generation' + }, + rerankModel: { + label: 'ReRank Model', + desc: 'Model for re-ranking search results (optional)' + }, contextTemplate: { label: 'Retrieval Result Summary Prompt', desc: 'Prompt template for generating answers based on retrieval results in normal mode', - placeholder: 'Enter the prompt template for retrieval result summary...' + placeholder: 'Enter the prompt template for retrieval result summary...', + custom: 'Custom template', + disabledHint: 'Currently using the default summary prompt. Enable custom to edit below.' }, systemPrompt: { label: 'System Prompt', desc: 'System-level prompt for normal mode conversations', - placeholder: 'Enter the system prompt...' + placeholder: 'Enter the system prompt...', + custom: 'Custom prompt', + disabledHint: 'Currently using the default prompt. Enable custom to edit below.' }, temperature: { label: 'Temperature', @@ -1389,11 +1480,39 @@ export default { label: 'Max Tokens', desc: 'Maximum number of tokens to generate in the response' }, + resetSystemPrompt: { + header: 'Reset to Default System Prompt', + body: 'Are you sure you want to reset to the default system prompt?' + }, + resetContextTemplate: { + header: 'Reset to Default Summary Prompt', + body: 'Are you sure you want to reset to the default summary prompt?' + }, toasts: { + chatModelSaved: 'LLM model saved', + rerankModelSaved: 'ReRank model saved', contextTemplateSaved: 'Retrieval result summary prompt saved', systemPromptSaved: 'System prompt saved', temperatureSaved: 'Temperature saved', - maxTokensSaved: 'Max tokens saved' + maxTokensSaved: 'Max tokens saved', + maxRoundsSaved: 'History rounds saved', + embeddingSaved: 'Embedding TopK saved', + keywordThresholdSaved: 'Keyword threshold saved', + vectorThresholdSaved: 'Vector threshold saved', + rerankTopKSaved: 'ReRank TopK saved', + rerankThresholdSaved: 'ReRank threshold saved', + enableRewriteSaved: 'Query rewrite preference saved', + fallbackStrategySaved: 'Fallback strategy saved', + fallbackResponseSaved: 'Fallback response saved', + fallbackPromptSaved: 'Fallback prompt saved', + rewritePromptSystemSaved: 'Rewrite system prompt saved', + rewritePromptUserSaved: 'Rewrite user prompt saved', + customPromptEnabled: 'Custom prompt enabled', + defaultPromptEnabled: 'Using default prompt', + customContextTemplateEnabled: 'Custom summary prompt enabled', + defaultContextTemplateEnabled: 'Using default summary prompt', + resetSystemPromptSuccess: 'Reset to default system prompt', + resetContextTemplateSuccess: 'Reset to default summary prompt' } }, // New: MCP Settings diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts index 0cd96a701..16a4a0898 100644 --- a/frontend/src/i18n/locales/ru-RU.ts +++ b/frontend/src/i18n/locales/ru-RU.ts @@ -151,9 +151,12 @@ export default { settings: { title: 'Настройки', modelConfig: 'Настройки модели', + modelManagement: 'Управление моделями', agentConfig: 'Настройки агента', webSearchConfig: 'Сетевой поиск', mcpService: 'Сервис MCP', + conversationConfig: 'Настройки диалога', + conversationStrategy: 'Стратегия диалога', systemSettings: 'Настройки системы', tenantInfo: 'Информация о арендаторе', apiInfo: 'Информация API', diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts index 9b44df21e..64748267f 100644 --- a/frontend/src/i18n/locales/zh-CN.ts +++ b/frontend/src/i18n/locales/zh-CN.ts @@ -243,8 +243,10 @@ export default { settings: { title: "设置", modelConfig: "模型配置", + modelManagement: "模型管理", agentConfig: "Agent配置", conversationConfig: "对话设置", + conversationStrategy: "对话策略", webSearchConfig: "网络搜索", mcpService: "MCP服务", systemSettings: "系统设置", @@ -1156,8 +1158,8 @@ export default { title: "模型配置", description: "为知识库选择合适的 AI 模型", llmLabel: "LLM 大语言模型", - llmDesc: "用于对话和问答的大语言模型", - llmPlaceholder: "请选择 LLM 模型", + llmDesc: "用于总结和摘要的大语言模型（可选）", + llmPlaceholder: "请选择 LLM 模型（可选）", embeddingLabel: "Embedding 嵌入模型", embeddingDesc: "用于文本向量化的嵌入模型", embeddingPlaceholder: "请选择 Embedding 模型", @@ -1375,15 +1377,104 @@ export default { description: "配置对话模式的默认行为和参数，包括Agent模式和普通模式的Prompt设置", agentMode: "Agent模式", normalMode: "普通模式", + menus: { + modes: "模式设置", + models: "模型配置", + thresholds: "检索阈值", + advanced: "高级设置", + }, + models: { + description: "统一管理 Agent 和普通模式使用的对话/总结模型与 ReRank 模型", + chatGroupLabel: "思考 / 对话模型", + chatGroupDesc: "包含 Agent 推理与规划模型，以及普通模式默认的对话/总结模型", + chatModel: { + label: "普通模式默认对话模型", + desc: "普通模式默认使用的对话/总结模型，当会话未指定模型时生效", + placeholder: "请选择默认对话模型", + }, + rerankModel: { + label: "普通模式默认 ReRank 模型", + desc: "普通模式默认使用的重排序模型", + placeholder: "请选择默认 ReRank 模型", + }, + rerankGroupLabel: "ReRank 模型", + rerankGroupDesc: "包含 Agent 使用的重排序模型，以及普通模式默认 ReRank 模型", + }, + thresholds: { + description: "调整召回与重排序的阈值与 TopK，平衡准确率与性能", + }, + maxRounds: { + label: "历史保留轮数", + desc: "用于多轮上下文和问题改写的历史轮数", + }, + embeddingTopK: { + label: "Embedding TopK", + desc: "向量召回阶段保留的文档数量", + }, + keywordThreshold: { + label: "关键词阈值", + desc: "关键词检索的最低得分阈值", + }, + vectorThreshold: { + label: "向量阈值", + desc: "向量召回的最低相似度阈值", + }, + rerankTopK: { + label: "ReRank TopK", + desc: "重排序后进入答案生成的文档数量", + }, + rerankThreshold: { + label: "ReRank 阈值", + desc: "重排序阶段的最低得分阈值", + }, + enableRewrite: { + label: "开启问题改写", + desc: "多轮对话自动改写问题以获得更优召回", + }, + fallbackStrategy: { + label: "兜底策略", + desc: "检索无结果时采用的处理方式", + fixed: "固定回复", + model: "交给模型继续生成", + }, + fallbackResponse: { + label: "固定兜底回复", + desc: "当兜底策略为固定回复时返回的文本", + }, + fallbackPrompt: { + label: "兜底 Prompt", + desc: "当选择模型兜底时使用的提示模板", + }, + advanced: { + description: "配置问题改写、兜底策略等高级设置", + }, + rewritePrompt: { + system: "Rewrite System Prompt", + user: "Rewrite User Prompt", + desc: "控制问题改写的系统提示词", + userDesc: "控制问题改写的用户提示词", + }, + chatModel: { + label: "LLM 模型", + desc: "用于总结和摘要的大语言模型", + }, + rerankModel: { + label: "ReRank 模型", + desc: "用于搜索结果重排序的模型（可选）", + }, contextTemplate: { label: "总结Prompt", desc: "用于普通模式下基于检索结果生成回答的Prompt模板", placeholder: "请输入检索结果总结的Prompt模板...", + custom: "自定义模板", + disabledHint: "当前使用系统默认总结 Prompt，开启自定义后才会应用下方内容。", }, systemPrompt: { label: "系统Prompt", desc: "用于普通模式对话的系统级Prompt", placeholder: "请输入系统Prompt...", + custom: "自定义 Prompt", + disabledHint: "当前使用系统默认 Prompt，开启自定义后才会应用下方内容。", }, temperature: { label: "温度参数", @@ -1393,11 +1484,39 @@ export default { label: "最大Token数", desc: "生成回答的最大Token数量", }, + resetSystemPrompt: { + header: "恢复默认系统 Prompt", + body: "确定要恢复为系统默认的系统 Prompt 吗？", + }, + resetContextTemplate: { + header: "恢复默认总结 Prompt", + body: "确定要恢复为系统默认的总结 Prompt 吗？", + }, toasts: { + chatModelSaved: "LLM 模型已保存", + rerankModelSaved: "ReRank 模型已保存", contextTemplateSaved: "总结Prompt已保存", systemPromptSaved: "系统Prompt已保存", temperatureSaved: "温度参数已保存", maxTokensSaved: "最大Token数已保存", + maxRoundsSaved: "历史轮数已保存", + embeddingSaved: "Embedding TopK 已保存", + keywordThresholdSaved: "关键词阈值已保存", + vectorThresholdSaved: "向量阈值已保存", + rerankTopKSaved: "ReRank TopK 已保存", + rerankThresholdSaved: "ReRank 阈值已保存", + enableRewriteSaved: "问题改写开关已保存", + fallbackStrategySaved: "兜底策略已保存", + fallbackResponseSaved: "兜底回复已保存", + fallbackPromptSaved: "兜底 Prompt 已保存", + rewritePromptSystemSaved: "改写 System Prompt 已保存", + rewritePromptUserSaved: "改写 User Prompt 已保存", + customPromptEnabled: "已启用自定义 Prompt", + defaultPromptEnabled: "已使用系统默认 Prompt", + customContextTemplateEnabled: "已启用自定义总结 Prompt", + defaultContextTemplateEnabled: "已使用系统默认总结 Prompt", + resetSystemPromptSuccess: "已恢复为系统默认 Prompt", + resetContextTemplateSuccess: "已恢复为系统默认总结 Prompt", }, }, // 新增：MCP 设置 diff --git a/frontend/src/views/chat/components/botmsg.vue b/frontend/src/views/chat/components/botmsg.vue index 41cea3c4d..29eaf3960 100644 --- a/frontend/src/views/chat/components/botmsg.vue +++ b/frontend/src/views/chat/components/botmsg.vue @@ -226,7 +226,7 @@ onMounted(async () => { color: #333333; line-height: 1.6; /* 确保换行符正确显示 */ - white-space: pre-line; /* 保留换行符，但合并多个空格 */ + // white-space: pre-line; /* 保留换行符，但合并多个空格 */ } .markdown-content { diff --git a/frontend/src/views/settings/AgentSettings.vue b/frontend/src/views/settings/AgentSettings.vue index a7121a646..c83ce6983 100644 --- a/frontend/src/views/settings/AgentSettings.vue +++ b/frontend/src/views/settings/AgentSettings.vue @@ -1,11 +1,12 @@ @@ -371,6 +603,14 @@ import { useI18n } from 'vue-i18n' import { listModels, type ModelConfig } from '@/api/model' import { getAgentConfig, updateAgentConfig, getConversationConfig, updateConversationConfig, type AgentConfig, type ConversationConfig, type ToolDefinition, type PlaceholderDefinition } from '@/api/system' +const props = defineProps<{ + // 来自外部设置弹窗的子菜单 key: 'modes' | 'models' | 'thresholds' | 'advanced' + activeSubSection?: string +}>() + +// 当前子页面（模式、模型、阈值、高级） +const activeSection = computed(() => props.activeSubSection || 'modes') + const settingsStore = useSettingsStore() const router = useRouter() const { t } = useI18n() @@ -378,6 +618,38 @@ const { t } = useI18n() // Tab 状态 const activeTab = ref('agent') +const getDefaultConversationConfig = (): ConversationConfig => ({ + prompt: '', + context_template: '', + temperature: 0.3, + max_tokens: 2048, + use_custom_system_prompt: true, + use_custom_context_template: true, + max_rounds: 5, + embedding_top_k: 10, + keyword_threshold: 0.3, + vector_threshold: 0.5, + rerank_top_k: 5, + rerank_threshold: 0.5, + enable_rewrite: true, + fallback_strategy: 'fixed', + fallback_response: '', + fallback_prompt: '', + summary_model_id: '', + rerank_model_id: '', + rewrite_prompt_system: '', + rewrite_prompt_user: '', +}) + +const normalizeConversationConfig = (config?: Partial): ConversationConfig => ({ + ...getDefaultConversationConfig(), + ...config, +}) + +const conversationConfig = ref(getDefaultConversationConfig()) +const conversationConfigLoaded = ref(false) +const conversationSaving = ref(false) + // Agent 模式本地状态 const localMaxIterations = ref(5) const localTemperature = ref(0.7) @@ -392,12 +664,84 @@ const localContextTemplate = ref('') const localSystemPromptNormal = ref('') const localTemperatureNormal = ref(0.3) const localMaxTokens = ref(2048) -const conversationConfigLoaded = ref(false) let savedContextTemplate = '' let savedSystemPromptNormal = '' let savedTemperatureNormal = 0.3 let savedMaxTokens = 2048 +const localMaxRounds = ref(5) +const localEmbeddingTopK = ref(10) +const localKeywordThreshold = ref(0.3) +const localVectorThreshold = ref(0.5) +const localRerankTopK = ref(5) +const localRerankThreshold = ref(0.5) +const localEnableRewrite = ref(true) +const localFallbackStrategy = ref<'fixed' | 'model'>('fixed') +const localFallbackResponse = ref('') +const localFallbackPrompt = ref('') +const localRewritePromptSystem = ref('') +const localRewritePromptUser = ref('') +const localSummaryModelId = ref('') +const localConversationRerankModelId = ref('') + +// 普通模式 Prompt 是否自定义（关闭时使用系统默认） +const localUseCustomSystemPromptNormal = ref(true) +const localUseCustomContextTemplate = ref(true) + +const syncConversationLocals = () => { + const cfg = conversationConfig.value + localContextTemplate.value = cfg.context_template ?? '' + savedContextTemplate = localContextTemplate.value + localSystemPromptNormal.value = cfg.prompt ?? '' + savedSystemPromptNormal = localSystemPromptNormal.value + localTemperatureNormal.value = cfg.temperature ?? 0.3 + savedTemperatureNormal = localTemperatureNormal.value + localMaxTokens.value = cfg.max_tokens ?? 2048 + savedMaxTokens = localMaxTokens.value + + localMaxRounds.value = cfg.max_rounds ?? 5 + localEmbeddingTopK.value = cfg.embedding_top_k ?? 10 + localKeywordThreshold.value = cfg.keyword_threshold ?? 0.3 + localVectorThreshold.value = cfg.vector_threshold ?? 0.5 + localRerankTopK.value = cfg.rerank_top_k ?? 5 + localRerankThreshold.value = cfg.rerank_threshold ?? 0.5 + localEnableRewrite.value = cfg.enable_rewrite ?? true + localFallbackStrategy.value = (cfg.fallback_strategy as 'fixed' | 'model') || 'fixed' + localFallbackResponse.value = cfg.fallback_response ?? '' + localFallbackPrompt.value = cfg.fallback_prompt ?? '' + localRewritePromptSystem.value = cfg.rewrite_prompt_system ?? '' + localRewritePromptUser.value = cfg.rewrite_prompt_user ?? '' + localSummaryModelId.value = cfg.summary_model_id ?? '' + localConversationRerankModelId.value = cfg.rerank_model_id ?? '' + localUseCustomSystemPromptNormal.value = cfg.use_custom_system_prompt ?? true + localUseCustomContextTemplate.value = cfg.use_custom_context_template ?? true +} + +const saveConversationConfig = async (partial: Partial, toastMessage?: string) => { + if (!conversationConfigLoaded.value) return + + const payload = normalizeConversationConfig({ + ...conversationConfig.value, + ...partial, + }) + + try { + conversationSaving.value = true + const res = await updateConversationConfig(payload) + conversationConfig.value = normalizeConversationConfig(res.data ?? payload) + syncConversationLocals() + if (toastMessage) { + MessagePlugin.success(toastMessage) + } + } catch (error) { + console.error('保存对话配置失败:', error) + MessagePlugin.error(getErrorMessage(error)) + throw error + } finally { + conversationSaving.value = false + } +} + // 计算 Agent 是否就绪 const isAgentReady = computed(() => { // 必须有思考模型、Rerank 模型 且 至少选择一个工具 @@ -603,18 +947,9 @@ onMounted(async () => { if (!conversationConfigLoaded.value) { try { const convRes = await getConversationConfig() - const convConfig = convRes.data - - localContextTemplate.value = convConfig.context_template || '' - savedContextTemplate = convConfig.context_template || '' - localSystemPromptNormal.value = convConfig.prompt || '' - savedSystemPromptNormal = convConfig.prompt || '' - localTemperatureNormal.value = convConfig.temperature || 0.3 - savedTemperatureNormal = convConfig.temperature || 0.3 - localMaxTokens.value = convConfig.max_tokens || 2048 - savedMaxTokens = convConfig.max_tokens || 2048 - + conversationConfig.value = normalizeConversationConfig(convRes.data) conversationConfigLoaded.value = true + syncConversationLocals() } catch (error) { console.error('加载普通模式配置失败:', error) // 使用默认值 @@ -1280,22 +1615,86 @@ const handleContextTemplateChange = async () => { } try { - const config: ConversationConfig = { - prompt: localSystemPromptNormal.value, - context_template: localContextTemplate.value, - temperature: localTemperatureNormal.value, - max_tokens: localMaxTokens.value - } - - await updateConversationConfig(config) + await saveConversationConfig( + { + context_template: localContextTemplate.value, + use_custom_context_template: localUseCustomContextTemplate.value, + }, + t('conversationSettings.toasts.contextTemplateSaved') + ) savedContextTemplate = localContextTemplate.value - MessagePlugin.success(t('conversationSettings.toasts.contextTemplateSaved')) } catch (error) { console.error('保存Context Template失败:', error) MessagePlugin.error(getErrorMessage(error)) } } +const reloadConversationConfig = async () => { + const convRes = await getConversationConfig() + conversationConfig.value = normalizeConversationConfig(convRes.data) + syncConversationLocals() +} + +const handleUseCustomSystemPromptNormalToggle = async (value: boolean) => { + if (!conversationConfigLoaded.value) return + + try { + if (!value) { + await saveConversationConfig( + { + prompt: '', + use_custom_system_prompt: false, + }, + t('conversationSettings.toasts.defaultPromptEnabled') + ) + await reloadConversationConfig() + } else { + await saveConversationConfig( + { + prompt: localSystemPromptNormal.value, + use_custom_system_prompt: true, + }, + t('conversationSettings.toasts.customPromptEnabled') + ) + savedSystemPromptNormal = localSystemPromptNormal.value + } + } catch (error) { + console.error('切换普通模式 System Prompt 自定义失败:', error) + MessagePlugin.error(getErrorMessage(error)) + localUseCustomSystemPromptNormal.value = !value + } +} + +const handleUseCustomContextTemplateToggle = async (value: boolean) => { + if (!conversationConfigLoaded.value) return + + try { + if (!value) { + await saveConversationConfig( + { + context_template: '', + use_custom_context_template: false, + }, + t('conversationSettings.toasts.defaultContextTemplateEnabled') + ) + await reloadConversationConfig() + } else { + await saveConversationConfig( + { + context_template: localContextTemplate.value, + use_custom_context_template: true, + }, + t('conversationSettings.toasts.customContextTemplateEnabled') + ) + savedContextTemplate = localContextTemplate.value + } + } catch (error) { + console.error('切换普通模式 Context Template 自定义失败:', error) + MessagePlugin.error(getErrorMessage(error)) + localUseCustomContextTemplate.value = !value + } +} + const handleSystemPromptNormalChange = async () => { if (!conversationConfigLoaded.value) return @@ -1304,16 +1703,14 @@ const handleSystemPromptNormalChange = async () => { } try { - const config: ConversationConfig = { - prompt: localSystemPromptNormal.value, - context_template: localContextTemplate.value, - temperature: localTemperatureNormal.value, - max_tokens: localMaxTokens.value - } - - await updateConversationConfig(config) + await saveConversationConfig( + { + prompt: localSystemPromptNormal.value, + use_custom_system_prompt: localUseCustomSystemPromptNormal.value, + }, + t('conversationSettings.toasts.systemPromptSaved') + ) savedSystemPromptNormal = localSystemPromptNormal.value - MessagePlugin.success(t('conversationSettings.toasts.systemPromptSaved')) } catch (error) { console.error('保存System Prompt失败:', error) MessagePlugin.error(getErrorMessage(error)) @@ -1324,16 +1721,11 @@ const handleTemperatureNormalChange = async (value: number) => { if (!conversationConfigLoaded.value) return try { - const config: ConversationConfig = { - prompt: localSystemPromptNormal.value, - context_template: localContextTemplate.value, - temperature: value, - max_tokens: localMaxTokens.value - } - - await updateConversationConfig(config) + await saveConversationConfig( + { temperature: value }, + t('conversationSettings.toasts.temperatureSaved') + ) savedTemperatureNormal = value - MessagePlugin.success(t('conversationSettings.toasts.temperatureSaved')) } catch (error) { console.error('保存Temperature失败:', error) MessagePlugin.error(getErrorMessage(error)) @@ -1344,21 +1736,177 @@ const handleMaxTokensChange = async (value: number) => { if (!conversationConfigLoaded.value) return try { - const config: ConversationConfig = { - prompt: localSystemPromptNormal.value, - context_template: localContextTemplate.value, - temperature: localTemperatureNormal.value, - max_tokens: value - } - - await updateConversationConfig(config) + await saveConversationConfig( + { max_tokens: value }, + t('conversationSettings.toasts.maxTokensSaved') + ) savedMaxTokens = value - MessagePlugin.success(t('conversationSettings.toasts.maxTokensSaved')) } catch (error) { console.error('保存Max Tokens失败:', error) MessagePlugin.error(getErrorMessage(error)) } } + +const handleMaxRoundsChange = async (value: number) => { + try { + await saveConversationConfig({ max_rounds: value }, t('conversationSettings.toasts.maxRoundsSaved')) + } catch (error) { + console.error('保存 max_rounds 失败:', error) + localMaxRounds.value = conversationConfig.value.max_rounds + } +} + +const handleEmbeddingTopKChange = async (value: number) => { + try { + await saveConversationConfig({ embedding_top_k: value }, t('conversationSettings.toasts.embeddingSaved')) + } catch (error) { + console.error('保存 embedding_top_k 失败:', error) + localEmbeddingTopK.value = conversationConfig.value.embedding_top_k + } +} + +const handleKeywordThresholdChange = async (value: number) => { + try { + await saveConversationConfig({ keyword_threshold: value }, t('conversationSettings.toasts.keywordThresholdSaved')) + } catch (error) { + console.error('保存 keyword_threshold 失败:', error) + localKeywordThreshold.value = conversationConfig.value.keyword_threshold + } +} + +const handleVectorThresholdChange = async (value: number) => { + try { + await saveConversationConfig({ vector_threshold: value }, t('conversationSettings.toasts.vectorThresholdSaved')) + } catch (error) { + console.error('保存 vector_threshold 失败:', error) + localVectorThreshold.value = conversationConfig.value.vector_threshold + } +} + +const handleRerankTopKChange = async (value: number) => { + try { + await saveConversationConfig({ rerank_top_k: value }, t('conversationSettings.toasts.rerankTopKSaved')) + } catch (error) { + console.error('保存 rerank_top_k 失败:', error) + localRerankTopK.value = conversationConfig.value.rerank_top_k + } +} + +const handleRerankThresholdChange = async (value: number) => { + try { + await saveConversationConfig({ rerank_threshold: value }, t('conversationSettings.toasts.rerankThresholdSaved')) + } catch (error) { + console.error('保存 rerank_threshold 失败:', error) + localRerankThreshold.value = conversationConfig.value.rerank_threshold + } +} + +const handleEnableRewriteChange = async (value: boolean) => { + try { + await saveConversationConfig({ enable_rewrite: value }, t('conversationSettings.toasts.enableRewriteSaved')) + } catch (error) { + console.error('保存 enable_rewrite 失败:', error) + localEnableRewrite.value = conversationConfig.value.enable_rewrite + } +} + +const handleFallbackStrategyChange = async (value: 'fixed' | 'model') => { + try { + await saveConversationConfig({ fallback_strategy: value }, t('conversationSettings.toasts.fallbackStrategySaved')) + } catch (error) { + console.error('保存 fallback_strategy 失败:', error) + localFallbackStrategy.value = (conversationConfig.value.fallback_strategy as 'fixed' | 'model') || 'fixed' + } +} + +const handleFallbackResponseChange = async () => { + if (localFallbackResponse.value === (conversationConfig.value.fallback_response ?? '')) return + try { + await saveConversationConfig({ fallback_response: localFallbackResponse.value }, t('conversationSettings.toasts.fallbackResponseSaved')) + } catch (error) { + console.error('保存 fallback_response 失败:', error) + localFallbackResponse.value = conversationConfig.value.fallback_response ?? '' + } +} + +const handleRewritePromptSystemChange = async () => { + if (localRewritePromptSystem.value === (conversationConfig.value.rewrite_prompt_system ?? '')) return + try { + await saveConversationConfig({ rewrite_prompt_system: localRewritePromptSystem.value }, t('conversationSettings.toasts.rewritePromptSystemSaved')) + } catch (error) { + console.error('保存 rewrite_prompt_system 失败:', error) + localRewritePromptSystem.value = conversationConfig.value.rewrite_prompt_system ?? '' + } +} + +const handleRewritePromptUserChange = async () => { + if (localRewritePromptUser.value === (conversationConfig.value.rewrite_prompt_user ?? '')) return + try { + await saveConversationConfig({ rewrite_prompt_user: localRewritePromptUser.value }, t('conversationSettings.toasts.rewritePromptUserSaved')) + } catch (error) { + console.error('保存 rewrite_prompt_user 失败:', error) + localRewritePromptUser.value = conversationConfig.value.rewrite_prompt_user ?? '' + } +} + +const handleFallbackPromptChange = async () => { + if (localFallbackPrompt.value === (conversationConfig.value.fallback_prompt ?? '')) return + try { + await saveConversationConfig({ fallback_prompt: localFallbackPrompt.value }, t('conversationSettings.toasts.fallbackPromptSaved')) + } catch (error) { + console.error('保存 fallback_prompt 失败:', error) + localFallbackPrompt.value = conversationConfig.value.fallback_prompt ?? '' + } +} + +const navigateToModelSettings = (subsection: 'chat' | 'rerank') => { + router.push('/platform/settings') + + setTimeout(() => { + const event = new CustomEvent('settings-nav', { + detail: { section: 'models', subsection }, + }) + window.dispatchEvent(event) + + setTimeout(() => { + const selector = subsection === 'rerank' ? '[data-model-type="rerank"]' : '[data-model-type="chat"]' + const element = document.querySelector(selector) + if (element) { + element.scrollIntoView({ behavior: 'smooth', block: 'start' }) + } + }, 200) + }, 100) +} + +const handleConversationSummaryModelChange = async (value: string) => { + if (value === '__add_model__') { + localSummaryModelId.value = conversationConfig.value.summary_model_id ?? '' + navigateToModelSettings('chat') + return + } + + try { + await saveConversationConfig({ summary_model_id: value }, t('conversationSettings.toasts.chatModelSaved')) + } catch (error) { + console.error('保存 summary_model_id 失败:', error) + localSummaryModelId.value = conversationConfig.value.summary_model_id ?? '' + } +} + +const handleConversationRerankModelChange = async (value: string) => { + if (value === '__add_model__') { + localConversationRerankModelId.value = conversationConfig.value.rerank_model_id ?? '' + navigateToModelSettings('rerank') + return + } + + try { + await saveConversationConfig({ rerank_model_id: value }, t('conversationSettings.toasts.rerankModelSaved')) + } catch (error) { + console.error('保存 rerank_model_id 失败:', error) + localConversationRerankModelId.value = conversationConfig.value.rerank_model_id ?? '' + } +}