diff --git a/docs/v0.3.0/advanced/agents-config.md b/docs/v0.3.0/advanced/agents-config.md deleted file mode 100644 index 55ad8099..00000000 --- a/docs/v0.3.0/advanced/agents-config.md +++ /dev/null @@ -1,63 +0,0 @@ -# 智能体 - -## 智能体开发 - -系统基于 [LangGraph](https://github.com/langchain-ai/langgraph) 并通过统一的 `AgentManager` 管理所有智能体。`src/agents/__init__.py` 会在启动时遍历 `src/agents` 目录，对每个包含 `__init__.py` 的子包执行自动发现：所有继承 `BaseAgent` 的类都会被注册并立即初始化，因此只要代码落位正确，就不需要再手动登记或修改管理器。 - -仓库预置了若干可直接运行的智能体：`chatbot` 聚焦对话与动态工具调度，`mini_agent` 提供精简模板，`reporter` 演示报告类链路。这些目录展示了上下文类、Graph 构造方式、子智能体引用以及中间件组合的范例，新增功能时可以直接复用。 - -### 创建新的智能体 - -在 `src/agents` 下新建一个包，保持与现有目录一致的结构：放置 Graph 构造逻辑（通常命名为 `graph.py`），并在包内的 `__init__.py` 中暴露主类。 - -智能体类必须继承 `src.agents.common.BaseAgent`，同时实现异步的 `get_graph` 方法来返回编译后的 LangGraph 实例，并配置好 `checkpointer`，否则无法从历史对话中恢复。 - -需要额外上下文字段时，可继承 `BaseContext` 构建自己的配置表单，再把类绑定到 `context_schema`，平台会在 `saves/agents/` 下生成默认配置。 - -案例1 使用内置工具构建一个极简的智能体，可以动态选择 Prompt 和 LLM： - -<<< @/../src/agents/mini_agent/graph.py - -案例2 基于MySQL工具，以及自定义 MCP Server 的数据库报表助手。 - -<<< @/../src/agents/reporter/graph.py - - - -智能体实例的生命周期交给管理器处理，会在自动发现时完成初始化并缓存单例，以便快速响应请求。在容器内热重载时，只要保存文件即可触发重新导入；需要强制刷新可调用 `agent_manager.get_agent(, reload=True)`。 - -更多动态工具选择与 MCP 注册的例子，见 `src/agents/chatbot/graph.py` 中的中间件组合。 - -### 拓展现有智能体 - -智能体保持为 LangGraph 的标准节点组合，因此可以在原有 `graph.py` 中添加节点、条件与消息转换器。复用现成上下文时，只需扩展当前 `context_schema` 的字段；若功能差异较大，可以创建新的上下文类并替换 `context_schema`。 - -对工具、模型或提示语的调整建议封装到中间件或独立函数里，既方便多智能体共用，又能保持 `BaseAgent` 的基础接口稳定。变更提交后无需手动刷新注册表，只要确保包结构未改变，智能体会在热重载中自动更新。 - -### 子智能体与中间件 - -子智能体集中放在 `src/agents/common/subagents` 目录，典型例子是 `calc_agent`，它通过 LangChain 的 `create_agent` 构建计算器能力并以工具暴露给主图。新增子智能体时沿用这一结构：在目录内编写封装函数与 `@tool` 装饰器，导出后即可被任意智能体调用。 - -中间件位于 `src/agents/common/middlewares`，包含上下文感知提示词、模型选择以及动态工具加载等实现。如果需要编写新的中间件，请遵循 LangChain 官方文档中对 `AgentMiddleware`、`ModelRequest`、`ModelResponse` 等接口的定义，完成后在该目录的 `__init__.py` 暴露入口，主智能体即可在 `middleware` 列表中引用。 - -## 内置工具与 MCP 集成 - -系统会根据配置自动组装工具集合，涵盖知识图谱查询、向量检索生成的动态工具、MySQL 只读查询能力、Tavily 搜索以及所有注册的 MCP 工具。 - -工具的启用状态和描述由配置文件或环境变量决定，当依赖缺失时会被中间件自动忽略，从而避免在图中加载不可用能力。MCP Server 的接入方式保持不变，只需在 `src/agents/common/mcp.py` 的 `MCP_SERVERS` 中填入服务地址与 `transport` 类型，如需更多范式可参阅 LangChain 官方文档。 - -### MySQL 数据库 - -设置数据库连接时，在 `.env` 中提供以下字段： - -```env -MYSQL_HOST=192.168.1.100 -MYSQL_USER=username -MYSQL_PASSWORD=your_secure_password -MYSQL_DATABASE=database_name -MYSQL_DATABASE_DESCRIPTION=业务主库（可选提示） -MYSQL_PORT=3306 -MYSQL_CHARSET=utf8mb4 -``` - -所有查询限定在只读范围（SELECT、SHOW、DESCRIBE、EXPLAIN），请求会经过表名校验与超时控制，默认限制 60 秒与 100 行输出，并可通过配置调整上限。连接信息会反馈给 LangGraph，智能体可以自动陈述数据库用途并选择更准确的检索策略。 diff --git a/docs/v0.3.0/advanced/branding.md b/docs/v0.3.0/advanced/branding.md deleted file mode 100644 index d8ed4b84..00000000 --- a/docs/v0.3.0/advanced/branding.md +++ /dev/null @@ -1,49 +0,0 @@ -# 品牌自定义 - -系统支持完整的品牌信息自定义，包括 Logo、组织名称、版权信息等。 - -## 配置方法 - -### 1. 复制模板文件 - -```bash -cp src/config/static/info.template.yaml src/config/static/info.local.yaml -``` - -### 2. 编辑品牌信息 - -在 `src/config/static/info.local.yaml` 中配置： - -<<< @/../src/config/static/info.template.yaml - -### 3. 环境变量配置 - -在 `.env` 文件中指定配置文件路径： - -```bash -YUXI_BRAND_FILE_PATH=src/config/static/info.local.yaml -``` - -::: tip 配置优先级 -`info.local.yaml` > `info.template.yaml`（默认） -::: - - -## 样式定制 - -系统配色主要保存在 `web/src/assets/css/base.css` 中： - -- 替换 `--main-*` 相关变量即可改变配色 -- 支持主题色、辅助色等完整定制 -- 实时预览，无需重启服务 - -**主要变量**: - -```css -:root { - --main-color: #1890ff; /* 主色调 */ - --main-bg: #f0f2f5; /* 背景色 */ - --main-text: #262626; /* 文字色 */ - --main-border: #d9d9d9; /* 边框色 */ -} -``` diff --git a/docs/v0.3.0/advanced/configuration.md b/docs/v0.3.0/advanced/configuration.md deleted file mode 100644 index 72e9e679..00000000 --- a/docs/v0.3.0/advanced/configuration.md +++ /dev/null @@ -1,185 +0,0 @@ -# 配置系统详解 - -## 概述 - -Yuxi-Know 从 v0.3.x 版本开始采用了全新的配置系统，基于 Pydantic BaseModel 和 TOML 格式，提供了类型安全、智能提示和选择性持久化等现代化特性。 - -## 架构设计 - -### 配置层次结构 - -``` -配置系统架构 -├── 默认配置 (代码定义) -│ ├── src/config/static/models.py (模型配置) -│ └── src/config/app.py (应用配置) -├── 用户配置 (TOML 文件) -│ └── saves/config/base.toml (仅保存用户修改) -└── 环境变量 (运行时覆盖) - └── .env 文件 -``` - -### 核心组件 - -#### 1. Config 类 (`src/config/app.py`) - -主配置类，继承自 Pydantic BaseModel，提供： - -- **类型验证**: 自动检查配置项类型 -- **默认值管理**: 内置合理的默认配置 -- **选择性持久化**: 仅保存用户修改的配置项 -- **向后兼容**: 支持旧的字典式访问方式 - -```python -class Config(BaseModel): - # 功能开关 - enable_reranker: bool = Field(default=False, description="是否开启重排序") - enable_content_guard: bool = Field(default=False, description="是否启用内容审查") - - # 模型配置 - default_model: str = Field(default="siliconflow/deepseek-ai/DeepSeek-V3.2-Exp") - embed_model: str = Field(default="siliconflow/BAAI/bge-m3") - - # 运行时状态 (不持久化) - model_provider_status: dict[str, bool] = Field(exclude=True) -``` - -#### 2. 模型配置类 (`src/config/static/models.py`) - -定义了三种类型的模型配置： - -- **ChatModelProvider**: 聊天模型提供商 -- **EmbedModelInfo**: 嵌入模型信息 -- **RerankerInfo**: 重排序模型信息 - -```python -class ChatModelProvider(BaseModel): - name: str = Field(..., description="提供商显示名称") - url: str = Field(..., description="提供商文档或模型列表 URL") - base_url: str = Field(..., description="API 基础 URL") - default: str = Field(..., description="默认模型名称") - env: str = Field(..., description="API Key 环境变量名") - models: list[str] = Field(default_factory=list, description="支持的模型列表") -``` - -添加配置： - - -```python -# 1. 在 DEFAULT_CHAT_MODEL_PROVIDERS 中添加 -"new-provider": ChatModelProvider( - name="新提供商", - url="https://provider.com/docs", - base_url="https://api.provider.com/v1", - default="default-model", - env="NEW_PROVIDER_API_KEY", - models=["model1", "model2"], -), - -# 2. 在 .env 中配置 API Key -# NEW_PROVIDER_API_KEY=your_api_key - -# 3. 重启服务或重新加载配置 -``` - -## 配置管理特性 - -系统只会保存用户修改过的配置项： - -```python -# 用户只修改了 enable_reranker -config.enable_reranker = True -config.save() # 只保存 enable_reranker 到 TOML 文件 - -# TOML 文件内容 -# enable_reranker = true -``` - -### 默认模型配置 (`src/config/static/models.py`) - -包含所有支持的模型提供商的默认配置，开发者可以直接修改此文件添加新的模型： - -```python -DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = { - "siliconflow": ChatModelProvider( - name="SiliconFlow", - url="https://cloud.siliconflow.cn/models", - base_url="https://api.siliconflow.cn/v1", - default="deepseek-ai/DeepSeek-V3.2-Exp", - env="SILICONFLOW_API_KEY", - models=[ - "deepseek-ai/DeepSeek-V3.2-Exp", - "Qwen/Qwen3-235B-A22B-Instruct-2507", - # ... - ], - ), - # 更多提供商... -} -``` - -### 用户配置 (`saves/config/base.toml`) - -只包含用户修改过的配置项，使用 TOML 格式： - -```toml -# 用户只修改了这些配置项 -enable_reranker = true -default_agent_id = "MyCustomAgent" -enable_content_guard = true - -# 模型配置修改 -[model_names.siliconflow] -models = [ - "deepseek-ai/DeepSeek-V3.2-Exp", - "custom-model-name", -] -``` - -## 高级配置 - -### 动态配置更新 - -```python -from src.config import config - -# 更新配置 -config.enable_reranker = True -config.default_agent_id = "CustomAgent" - -# 更新模型列表 -config.model_names["siliconflow"].models.append("new-model") - -# 保存配置 -config.save() - -# 或者只保存特定提供商的模型配置 -config._save_models_to_file("siliconflow") -``` - -### 配置验证 - -```python -# 验证配置 -from src.config import config - -# 检查模型提供商可用性 -for provider, status in config.model_provider_status.items(): - print(f"{provider}: {'✅' if status else '❌'}") - -# 获取可用模型列表 -available_models = config.get_model_choices() -available_embed_models = config.get_embed_model_choices() -available_rerankers = config.get_reranker_choices() -``` - -### 配置导出 - -```python -# 导出完整配置（包含运行时状态） -full_config = config.dump_config() - -# 导出用户配置（仅保存到文件的部分） -user_config = { - field: getattr(config, field) - for field in config._user_modified_fields -} diff --git a/docs/v0.3.0/advanced/document-processing.md b/docs/v0.3.0/advanced/document-processing.md deleted file mode 100644 index 1e4a2d99..00000000 --- a/docs/v0.3.0/advanced/document-processing.md +++ /dev/null @@ -1,152 +0,0 @@ -# 文档处理与 OCR - -系统提供 4 种文档处理选项： - -- **RapidOCR**: CPU 友好，无需 GPU，适合基础文字识别 -- **MinerU**: 本地化高精度 VLM 解析，适合复杂 PDF 和表格文档 -- **MinerU Official**: 官方云服务 API，无需本地部署，开箱即用 -- **PaddleX**: 结构化解析，适合表格、票据等特殊格式 - -## 快速配置 - -### 1. 基础 OCR (RapidOCR) - -```bash -# 下载模型 -hf download SWHL/RapidOCR --local-dir ./models/SWHL/RapidOCR - -# 启动服务 -docker compose up -d api -``` - -### 2. 高精度 OCR (MinerU) - -需要配置： - -```bash -MINERU_VL_SERVER=http://localhost:30000 -MINERU_API_URI=http://localhost:30001 -``` - -然后启动相关服务 - -```bash -# 需要 GPU，启动 MinerU 服务 -docker compose up -d mineru-vllm-server mineru-api - -# 启动主服务 -docker compose up -d api -``` - -### 3. 官方云服务 (MinerU Official) - - -API 密钥可以从 [MinerU 官网](https://mineru.net) 申请。 - -```bash -# 设置 API 密钥环境变量 -export MINERU_API_KEY="your-api-key-here" - -# 启动主服务 -docker compose up -d api -``` - -### 4. 结构化解析 (PaddleX) - -```bash -# 需要 GPU，启动 PaddleX 服务 -docker compose up -d paddlex - -# 启动主服务 -docker compose up -d api -``` - -## 处理器选择 - -| 处理器 | 适用场景 | 硬件要求 | 特点 | -|--------|----------|------------|------| -| **RapidOCR** | 基础文字识别 | CPU | 速度快，资源占用低 | -| **MinerU** | 复杂 PDF、表格、公式 | GPU | 精度高，版面分析好 | -| **MinerU Official** | 复杂文档解析（云服务） | 无特殊要求 | 官方云服务，开箱即用，有 API 配额 | -| **PaddleX** | 表格、票据、结构化文档 | GPU | 专业版面解析 | - -## 参数说明 - -### enable_ocr 选项 -- `disable`: 不启用 OCR（PDF 按文本提取，图片**必须选择 OCR 方式**） -- `onnx_rapid_ocr`: RapidOCR 处理 -- `mineru_ocr`: MinerU HTTP API 处理 -- `mineru_official`: MinerU 官方云服务 API 处理 -- `paddlex_ocr`: PaddleX 处理 - -### 注意事项 -- **图片文件必须启用 OCR**，否则无法提取内容 -- MinerU 和 PaddleX 需要 GPU 支持 -- MinerU Official 需要设置 `MINERU_API_KEY` 环境变量 -- RapidOCR 适合 CPU 环境和基础识别需求 - -## 故障排除 - -### 常见问题 - -1. **RapidOCR 模型不存在** - ```bash - # 下载模型 - huggingface-cli download SWHL/RapidOCR --local-dir ./models/SWHL/RapidOCR - ``` - -2. **GPU 服务连接失败** - ```bash - # 检查服务状态 - docker compose ps - - # 查看日志 - docker compose logs mineru - ``` - -3. **健康检查** - ```bash - # 检查所有 OCR 服务状态 - curl http://localhost:5050/system/health/ocr-services - ``` - -## 批量处理脚本 - -系统提供便捷的批量处理脚本，用于高效批量上传文档。 - -### 文件上传脚本 - -使用 `scripts/batch_upload.py` 批量上传文件到知识库： - -```bash -# 批量上传文档（多种格式） -uv run scripts/batch_upload.py \ - --db-id kb_b2730ad6801b149694021106c7eddd38 \ - --directory data.nogit/农业农村局 \ - --pattern "*.docx" --pattern "*.txt" --pattern "*.html" \ - --base-url http://172.19.13.6:5050/api \ - --username admin \ - --password admin123 \ - --batch-size 20 \ - --wait-for-completion \ - --poll-interval 5 \ - --recursive \ - --enable-ocr mineru_ocr \ # mineru_official, paddlex_ocr, onnx_rapid_ocr - --record-file scripts/tmp/batch_processed_files_1029.txt -``` - -**参数说明**: -- `--db-id`: 目标知识库 ID -- `--directory`: 文件目录路径 -- `--pattern`: 文件匹配模式，可以多次指定以支持多种格式（例如：`--pattern "*.docx" --pattern "*.pdf" --pattern "*.html"`） -- `--batch-size`: 每批处理的文件数量（默认20） -- `--wait-for-completion`: 是否等待任务完成再处理下一批（默认开启） -- `--poll-interval`: 任务状态检查间隔，单位秒（默认5秒） -- `--recursive`: 递归处理子目录 -- `--record-file`: 处理记录文件路径 - -**注意事项**: -- 系统按"内容哈希"进行去重；同一知识库已存在相同内容的文件会被拒绝（409） -- 建议根据系统性能调整批次大小 -- 大量文件处理时建议开启分批等待功能 -- 先上传后处理的机制更稳定，适合大批量文档导入 diff --git a/docs/v0.3.0/advanced/misc.md b/docs/v0.3.0/advanced/misc.md deleted file mode 100644 index 2dfdd422..00000000 --- a/docs/v0.3.0/advanced/misc.md +++ /dev/null @@ -1,53 +0,0 @@ -# 其他配置 - -## 内容安全 - -系统内置内容审查机制（默认是关闭状态），保障服务内容的合规性。目前配置了关键词过滤以及 LLM 对内容进行审查。管理员可在 `设置` → `基本设置` 页面中进行配置并选择安全模型。 - -检测流程为，接收到用户输入之后，就对用户的输入进行检测是否合规，同时在流式传输的过程中进行实时检测（仅关键词）。当流式输出结束之后，则开始检测整个内容。 -**注意**，使用 LLM 检测虽然可以大大缓解提示词注入带来的问题，但也会在用户交互上带来延迟影响，需要考虑是否启用。 - -对于关键词检测，敏感词词库位于 `src/config/static/bad_keywords.txt` 文件，每行一个关键词，实时生效，无需重启服务。 - -对于 LLM 检测，Prompt 可以看到 `src/plugins/guard.py`： - -<<< @/../src/plugins/guard.py#guard_prompt - -## 网页搜索 - -系统内置了基于 Tavily 的联网搜索能力，配置完成后，大模型会自动在需要时调用 `enable_web_search` 对应的工具，为回答提供实时网页信息。 - - -1. 前往 [Tavily 官网](https://app.tavily.com/) 注册并在控制台创建 API Key。 -2. 在项目根目录的 `.env`（或 `docker-compose.yml` 中的对应环境变量段）写入： - ```env - TAVILY_API_KEY=sk-xxxxxxxxxxxxxxxx - ``` -3. 重新加载服务使密钥生效，推荐执行： - ```bash - docker compose up -d api-dev web-dev - ``` - 若服务已运行，则使用 `docker compose restart api-dev` 即可。 - -完成以上步骤后，后端会自动将 `enable_web_search` 标记为启用，在智能体的工具配置区域即可看到这个工具，展示 Tavily 返回的实时结果。若需要关闭该能力，删除或清空 `TAVILY_API_KEY` 后再次重启服务即可。 - -## 服务端口 - -系统使用多个端口提供不同服务，以下是完整的端口映射： - -| 端口 | 服务 | 容器名称 | 说明 | -|------|------|----------|------| -| **5173** | Web 前端 | web-dev | 用户界面 | -| **5050** | API 后端 | api-dev | 核心服务 | -| **7474/7687** | Neo4j | graph | 图数据库 | -| **9000/9001** | MinIO | milvus-minio | 对象存储 | -| **19530/9091** | Milvus | milvus | 向量数据库 | -| **30000** | MinerU | mineru | PDF 解析（可选）| -| **8080** | PaddleX | paddlex-ocr | OCR 服务（可选）| -| **8081** | vLLM | - | 本地推理（可选）| - -::: tip 端口访问 -- Web 界面: `http://localhost:5173` -- API 文档: `http://localhost:5050/docs` -- Neo4j 管理: `http://localhost:7474` -::: diff --git a/docs/v0.3.0/changelog/0.3-release-notes.md b/docs/v0.3.0/changelog/0.3-release-notes.md deleted file mode 100644 index 7d8d5fbd..00000000 --- a/docs/v0.3.0/changelog/0.3-release-notes.md +++ /dev/null @@ -1,106 +0,0 @@ -# Yuxi-Know v0.3 更新说明 - -## 概览 - -Yuxi-Know v0.3 是一个重要的里程碑版本，包含了多项架构重构、功能增强和用户体验改进。本版本重点关注了系统架构的优化、数据存储的统一管理以及用户界面的现代化改进。 - -## 🔄 重大变更 (Breaking Changes) - -### 环境配置文件位置调整 -- **变更内容**: 将 `.env` 文件从 `src/.env` 移动到项目根目录 `.env` -- **影响**: 需要更新配置文件的复制命令和所有相关的文档引用 -- **迁移指南**: - ```bash - # 旧版本 - cp src/.env.template src/.env - - # 新版本 - cp .env.template .env - ``` - -### 配置文件管理调整 - -配置系统从 YAML 格式迁移到了基于 Pydantic BaseModel + TOML 的现代化配置系统。 - -| 项目 | v0.2.x | v0.3.x | -|------|--------|--------| -| 默认模型配置 | `src/config/static/models.yaml` | `src/config/static/models.py` | -| 用户配置 | `saves/config/base.yaml` | `saves/config/base.toml` | -| 配置格式 | YAML | Python 代码 + TOML | -| 类型安全 | ❌ 无 | ✅ Pydantic 验证 | -| IDE 支持 | ❌ 基础 | ✅ 完整智能提示 | -| 持久化策略 | 全量保存 | 选择性保存 | - - -示例：迁移自定义模型提供商 - -假设你的旧 `models.yaml` 中有： - -```yaml -# 旧的 models.yaml -MODEL_NAMES: - custom-provider: - name: "My Custom Provider" - base_url: "https://api.custom.com/v1" - default: "custom-model" - env: "CUSTOM_API_KEY" - models: - - "custom-model" - - "another-model" -``` - -需要在新的 `src/config/static/models.py` 中添加： - -```python -# 新的 models.py -DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = { - # ... 现有配置 ... - - "custom-provider": ChatModelProvider( - name="My Custom Provider", - url="https://custom.com/docs", - base_url="https://api.custom.com/v1", - default="custom-model", - env="CUSTOM_API_KEY", - models=["custom-model", "another-model"], - ), -} -``` - - -### 数据库存储架构重构 -- **变更内容**: 重新实现了对话管理的存储与管理，不再依赖于 MemorySaver -- **影响**: 使用新的存储结构，之前存储的历史记录无法直接迁移 -- **改进**: 所有对话记录统一保存到 `server.db` 中，提供更好的数据一致性和查询性能 - -### 自定义模型支持移除 -- **变更内容**: 完全移除自定义模型支持功能 -- **替代方案**: 使用自定义 provider - -## ✨ 新增功能 - -### 1. Dashboard 统计面板 -- **用户活跃度统计**: 提供用户使用情况的详细分析 -- **工具调用统计**: 实时监控各种工具的使用频率和效果 -- **知识库分析**: 展示知识库的使用情况和性能指标 -- **智能体分析**: 统计智能体的调用次数和成功率 -- **时间序列数据**: 支持历史趋势分析和可视化展示 - -### 2. 消息反馈系统 -- **点赞点踩功能**: 用户可以对 AI 回复进行质量评价 -- **反馈数据收集**: 为模型优化提供有价值的数据支持 -- **管理员视图**: 管理员可以查看整体的反馈统计情况 - -### 3. 用户资料增强 -- **用户名更新**: 支持用户修改显示名称 -- **头像管理**: 完善用户头像上传和管理功能 -- **账户安全**: 增强账户登录失败次数限制和锁定机制 - -### 4. 文档系统 -- **VitePress 集成**: 添加完整的官方文档站点 -- **快速开始指南**: 优化新用户的上手体验 -- **配置文档**: 详细的环境配置和功能说明 -- **GitHub Actions**: 实现文档的自动部署 - - -**注意**: v0.3 版本包含多项重大变更，建议在升级前仔细阅读本文档并做好数据备份。如有问题，请通过 GitHub Issues 反馈。 \ No newline at end of file diff --git a/docs/v0.3.0/changelog/contributing.md b/docs/v0.3.0/changelog/contributing.md deleted file mode 100644 index 9f77ead9..00000000 --- a/docs/v0.3.0/changelog/contributing.md +++ /dev/null @@ -1,125 +0,0 @@ -# 参与贡献 - -感谢所有贡献者的支持！ - - - 贡献者名单 - - -## 如何贡献 - -### 1. Fork 项目 - -在 GitHub 上 Fork 本项目到你的账户。 - -### 2. 创建分支 - -```bash -git checkout -b feature/amazing-feature -``` - -### 3. 提交更改 - -```bash -git commit -m 'feat: Add some amazing feature' -``` - -### 4. 推送分支 - -```bash -git push origin feature/amazing-feature -``` - -### 5. 创建 PR - -在 GitHub 上创建 Pull Request，详细描述你的更改内容。 - -## 开发指南 - -### 代码规范 - -- 遵循项目代码规范 -- Python 代码使用 `make format` 格式化 -- 使用 `make lint` 检查代码质量 -- 添加必要的测试用例 -- 更新相关文档 - -### 提交规范 - -使用清晰的提交信息： - -``` -feat: 添加新功能 -fix: 修复 bug -docs: 更新文档 -style: 代码格式调整 -refactor: 代码重构 -test: 添加测试 -chore: 构建过程或辅助工具的变动 -``` - - -## 🐞 Bug 修复发布流程 - -如果在发布 `v0.3.0` 后发现 bug： - -### ✅ 情况 1：main 上没有未完成的新功能 - -直接在 main 修复并发布： - -```bash -git commit -m "fix: resolve config parser crash" -git tag -a v0.3.1 -m "Hotfix v0.3.1" -git push origin main --tags -``` - -### ⚙️ 情况 2：main 上已有新功能未完成 - -从上一个 tag 建立 hotfix 分支： - -```bash -git checkout -b hotfix/0.3.1 v0.3.0 -# 修复问题 -git commit -m "fix: resolve config parser crash" -git push origin hotfix/0.3.1 - -# 测试后合并回 main 并打 tag -git checkout main -git merge --no-ff hotfix/0.3.1 -git tag -a v0.3.1 -m "Hotfix v0.3.1" -git push origin main --tags - -# 删除临时分支 -git branch -d hotfix/0.3.1 -git push origin --delete hotfix/0.3.1 -``` - - -### 测试要求 - -::: tip 测试 -- `make lint` / `make format` 保持代码整洁 -- `cp test/.env.test.example test/.env.test` 配置测试凭据 -- `make router-tests` 运行集成路由测试，支持 `PYTEST_ARGS="-k chat_router"` -- `uv run --group test pytest test/api` 可直接运行 pytest（容器内） -::: - -
-常用命令 - -```bash -# 全量路由测试 -make router-tests - -# 仅运行知识库相关用例 -make router-tests PYTEST_ARGS="-k knowledge_router" - -# 不经过 Makefile，直接调用 pytest -uv run --group test pytest test/api -vv -``` - -
- -## 许可证 - -本项目基于 MIT License 开源，贡献的代码将遵循相同的许可证。 diff --git a/docs/v0.3.0/changelog/faq.md b/docs/v0.3.0/changelog/faq.md deleted file mode 100644 index 5e0fad90..00000000 --- a/docs/v0.3.0/changelog/faq.md +++ /dev/null @@ -1,41 +0,0 @@ -# 常见问题 - -以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。 - -- 首次运行如何创建管理员？ - - Web 首次启动会引导初始化；也可调用 API： - - `GET /api/auth/check-first-run` → `first_run=true` 时 - - `POST /api/auth/initialize` 提交 `user_id` 与 `password` - - 无默认账号，初始化后使用创建的超级管理员登录 - -- 镜像拉取/构建失败？ - - 可使用 `docker/pull_image.sh` 辅助拉取，或配置代理环境变量 `HTTP_PROXY/HTTPS_PROXY` - - 若已配置代理仍失败，可临时取消代理后重试 - - 参考：介绍 → 快速开始 → 故障排除 - -- 服务端口与访问地址？ - - Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs` - - 端口一览与说明见：高级配置 → 其他配置 → 服务端口 - -- Milvus/Neo4j 启动或连接失败？ - - 重启：`docker compose up milvus -d && docker restart api-dev` - - Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474` - -- OCR 模型或服务不可用？ - - RapidOCR 本地模型：确保 `MODEL_DIR/SWHL/RapidOCR` 下存在 `PP-OCRv4` 模型 - - MinerU/PaddleX：检查健康检查接口与 GPU/CUDA 版本 - - 参考：高级配置 → 文档解析 - -- 支持的文件类型与常见入库失败？ - - 查询：`GET /api/knowledge/files/supported-types` - - 常见失败：不支持的扩展名、内容哈希重复（去重）、OCR 服务未就绪 - -- 批量上传与转换示例？ - - 上传入库：`uv run scripts/batch_upload.py upload --db-id --directory --username --password

--base-url http://127.0.0.1:5050/api` - - 参考：高级配置 → 文档解析 - -- 登录失败被锁定？ - - 多次失败会临时锁定账户，请根据提示等待后重试 - -- 如何查看日志和状态？ - - `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志 diff --git a/docs/v0.3.0/intro/knowledge-base.md b/docs/v0.3.0/intro/knowledge-base.md deleted file mode 100644 index 4e73845c..00000000 --- a/docs/v0.3.0/intro/knowledge-base.md +++ /dev/null @@ -1,137 +0,0 @@ -# 知识库与知识图谱 - -项目中的知识库与知识图谱，即是知识管理组织的方式，同时会被封装为工具供 AgenticRAG 系统调用。 - -## 创建知识库 - -系统支持多种知识库存储形式，满足不同场景需求： - -| 存储类型 | 特点 | 适用场景 | -|----------|------|----------| -| **Chroma** | 轻量级向量数据库 | 小型项目、快速原型、维护方便 | -| **Milvus** | 高性能向量数据库 | 大规模生产环境、高性能查询 | -| **LightRAG** | 图增强检索 | 复杂知识关系，构建成本较高 | - -访问 Web 界面：`http://localhost:5173`，进入"知识库管理"页面，点击"新建知识库"，填写知识库信息。 - -这里需要**注意**的是，这里的知识库的标题和描述都会作为智能体选择工具的依据，因此尽量详尽的描述该知识库。 - - -### LightRAG 知识库说明 - -在本项目中，系统支持基于 [LightRAG](https://github.com/HKUDS/LightRAG) 的知识图谱自动构建，能够从文档中自动提取实体和关系，构建结构化知识图谱。但是 LightRAG 所构建的知识图谱不作为全局的知识图谱来使用。只是将 LightRAG 作为知识的组织和检索形式。一方面是因为 LightRAG 构建的图谱的质量比较差，另一方面是不希望与全局的知识图谱弄混。 - -LightRAG 知识库可在知识库详情中可视化，但不支持在侧边栏图谱中直接检索，图谱检索工具不支持 LightRAG 知识库，查询需要使用对应的知识库作为工具。 - -在 Neo4j 的检索中可以看到，实际上 LightRAG 的节点和边依然是和知识图谱本身构建在了同一个 Neo4j 数据库中，但是使用了特殊的 tag 做区分。这点在后面介绍知识图谱的时候也会额外说明。 - - -系统默认使用 `siliconflow` 的 `Qwen/Qwen3-30B-A3B-Instruct-2507` 模型进行图谱构建。可通过环境变量自定义图谱构建模型： - -<<< @/../.env.template#lightrag{bash} - - -## 文档管理 - -本系统的“上传 → 解析入库 → 检索/可视化”流程既可通过 Web 界面完成，也可使用 API/脚本批量处理。 - -**支持的文件类型** - -- 文本与文档：`.txt`、`.md`、`.doc`、`.docx`、`.pdf` -- 网页与数据：`.html`、`.htm`、`.json`、`.csv`、`.xls`、`.xlsx` -- 图片：`.jpg`、`.jpeg`、`.png`、`.bmp`、`.tiff`、`.tif` - -接口查询：`GET /api/knowledge/files/supported-types` - -**上传与入库** - -1) 上传文件（返回服务端保存路径） -- `POST /api/knowledge/files/upload?db_id=<可选>` -- 成功返回：`file_path`（后续入库使用）、`content_hash`（内容去重） - -2) 解析并入库（异步任务） -- `POST /api/knowledge/databases/{db_id}/documents` -- 返回：`status=queued` 与 `task_id`，可在任务中心查看进度 - -去重策略：系统按“内容哈希”判断是否已存在相同文件，避免重复入库。 - -### 批量脚本 - -- 上传并入库：参见 `scripts/batch_upload.py upload` - -## 知识图谱 - -本项目存在两类“图谱相关”能力： - -- 全局知识图谱（Neo4j）：用于智能体工具 `query_knowledge_graph` 的图实体查询；统一保存在 Neo4j 中，提供三元组检索和系统级可视化。 -- LightRAG 知识库内图谱：针对某个知识库由 LightRAG 自动抽取实体/关系，用于该库内的图增强检索与可视化；与全局图共享同一 Neo4j 实例，但通过特殊 tag 区分，不作为全局图谱使用。 - -选择建议： -- 更结构化的库内检索/可视化：优先使用 LightRAG（注意构建质量与成本）。 -- 统一的图查询/工具调用：依赖全局 Neo4j 图谱与工具 `query_knowledge_graph`。 - -因此，侧边栏知识图谱页面展示的是 Neo4j 图数据库中符合以下规则的知识图谱信息。 - -具体展示内容包括： - -- 带有 Entity 标签的节点 -- 带有 RELATION 类型的关系边 - -注意： - -这里仅展示用户上传的实体和关系，不包含知识库中自动创建的图谱。 -查询逻辑基于图谱适配器的子图查询方法实现： - -```SQL -MATCH (n:Entity)-[r]->(m:Entity) -RETURN - {id: elementId(n), name: n.name} AS h, - {type: r.type, source_id: elementId(n), target_id: elementId(m)} AS r, - {id: elementId(m), name: m.name} AS t -LIMIT $num -``` - -如需查看完整的 Neo4j 数据库内容，请使用 "Neo4j 浏览器" 按钮访问 Neo4j 原生界面。 - -通过网页上传的 `jsonl` 文件的图谱默认会符合上述条件。 - - - -### 1. 以三元组形式导入 - - -系统支持通过网页导入 `jsonl` 格式的知识图谱数据： - -```jsonl -{"h": "北京", "t": "中国", "r": "首都"} -{"h": "上海", "t": "中国", "r": "直辖市"} -{"h": "深圳", "t": "广东", "r": "省会"} -``` - -**格式说明**，每行一个三元组，系统自动验证数据格式，并自动导入到 Neo4j 数据库，添加 `Upload`、`Entity`、`Relation` 标签，会自动处理重复的三元组。 - -Neo4j 访问信息可以参考 `docker-compose.yml` 中配置对应的环境变量来覆盖。 - -- **默认账户**: `neo4j` -- **默认密码**: `0123456789` -- **管理界面**: `http://localhost:7474` -- **连接地址**: bolt://localhost:7687 - -::: tip 测试数据 -可以使用 `test/data/A_Dream_of_Red_Mansions_tiny.jsonl` 文件进行测试导入。 -::: - -### 2. 接入已有 Neo4j 实例 - -如需接入已有的 Neo4j 实例，可修改 `.env` 中的配置： - -<<< @/../.env.template#neo4j{bash} - -同时记得注释掉下面的 neo4j 服务： - -<<< @/../docker-compose.yml#neo4j - - -::: warning 注意事项 -确保每个节点都有 `Entity` 标签，每个关系都有 `RELATION` 类型，否则会影响图的检索与构建功能。 -::: diff --git a/docs/v0.3.0/intro/model-config.md b/docs/v0.3.0/intro/model-config.md deleted file mode 100644 index e515a847..00000000 --- a/docs/v0.3.0/intro/model-config.md +++ /dev/null @@ -1,198 +0,0 @@ -# 模型配置 - -## 对话模型 - -系统支持多种大语言模型服务商，通过配置对应的 API 密钥即可使用： - -| 服务商 | 环境变量 | 特点 | -|--------|----------|------| -| [硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) | `SILICONFLOW_API_KEY` | 🆓 免费额度，默认推荐 | -| OpenAI | `OPENAI_API_KEY` | GPT 系列模型 | -| DeepSeek | `DEEPSEEK_API_KEY` | 国产大模型 | -| OpenRouter | `OPENROUTER_API_KEY` | 多模型聚合平台 | -| 智谱清言 | `ZHIPUAI_API_KEY` | GLM 系列模型 | -| 阿里云百炼 | `DASHSCOPE_API_KEY` | 通义千问系列 | - -其余还支持火山、Together、vLLM、Ollama 等。 - -### 配置方法 - -在 `.env` 文件中添加对应的环境变量： - -<<< @/../.env.template#model_provider{bash 2} - -### 默认对话模型格式 - -系统的默认对话模型通过配置项 `default_model` 指定，格式统一为 `模型提供商/模型名称`，例如： - -```yaml -default_model: siliconflow/deepseek-ai/DeepSeek-V3.2-Exp -``` - -在 Web 界面中选择模型时也会自动按照这一格式保存，无需手动拆分提供商和模型名称。 - - -::: tip 免费获取 API Key -[硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) 注册即送 14 元额度，支持多种开源模型。 -::: - -## 自定义模型供应商 - -::: warning -原本网页中的自定义模型已在 `0.3.x` 版本移除，请在 `src/config/static/models.py` 中按如下方式配置，并重启服务后选择并使用。此外，这里也推荐一下团队的另外一个小工具 [mvllm (Manage and Route vLLM Servers)](https://github.com/xerrors/mvllm)。 -::: - -::: tip 配置系统升级 (v0.3.x) -从 `v0.3.x` 版本开始，模型配置系统已升级为基于 Pydantic BaseModel 的类型安全配置，支持 TOML 格式的用户配置文件。 -- **默认配置**: `src/config/static/models.py` (Python 代码) -- **用户配置**: `saves/config/base.toml` (TOML 格式，仅保存用户修改) -::: - -系统理论上兼容任何 OpenAI 兼容的模型服务，包括： - -- **vLLM**: 高性能推理服务 -- **Ollama**: 本地模型管理 -- **API 中转服务**: 各种代理和聚合服务 - -如需添加新的模型供应商，请按以下步骤操作： - -### 1. 编辑模型配置文件 - -**方式一：修改默认配置（推荐）** -编辑 `src/config/static/models.py` 文件中的 `DEFAULT_CHAT_MODEL_PROVIDERS` 字典 - -在 `src/config/static/models.py` 中添加新的模型供应商： - -```python -DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = { - # ... 现有配置 ... - - "custom-provider": ChatModelProvider( - name="自定义提供商", - url="https://your-provider.com/docs", - base_url="https://api.your-provider.com/v1", - default="custom-model-name", - env="CUSTOM_API_KEY_ENV_NAME", - models=[ - "supported-model-name", - "another-model-name", - ], - ), - - # 本地 Ollama 服务 - "local-ollama": ChatModelProvider( - name="Local Ollama", - url="https://ollama.com", - base_url="http://localhost:11434/v1", - default="llama3.2", - env="NO_API_KEY", # 对于不需要API Key的服务，使用NO_API_KEY - models=["llama3.2", "qwen2.5"], - ), - - # 本地 vLLM 服务 - "local-vllm": ChatModelProvider( - name="Local vLLM", - url="https://docs.vllm.ai", - base_url="http://localhost:8000/v1", - default="Qwen/Qwen2.5-7B-Instruct", - env="NO_API_KEY", - models=[ - "Qwen/Qwen2.5-7B-Instruct", - "Qwen/Qwen2.5-14B-Instruct", - ], - ), -} -``` - -### 3. 配置环境变量 - -在 `.env` 文件中添加对应的环境变量： -```env -CUSTOM_API_KEY_ENV_NAME=your_api_key_here -``` - -### 4. 重新部署 - -```bash -docker compose restart api-dev -``` - -## 嵌入模型和重排序模型 - -::: warning 重要说明 -从 v0.2 版本开始，项目采用微服务架构，模型部署与项目本身完全解耦。如需使用本地模型，需要先通过 vLLM 或 Ollama 部署为 API 服务。 -::: - -### 本地模型部署 - -#### 1. 配置模型信息 - -在 `src/config/static/models.py` 中的默认配置部分添加： - -```python -# 默认嵌入模型配置 -DEFAULT_EMBED_MODELS: dict[str, EmbedModelInfo] = { - # ... 现有配置 ... - - "vllm/Qwen/Qwen3-Embedding-0.6B": EmbedModelInfo( - name="Qwen/Qwen3-Embedding-0.6B", - dimension=1024, - base_url="http://localhost:8000/v1/embeddings", - api_key="no_api_key", - ), -} - -# 默认重排序模型配置 -DEFAULT_RERANKERS: dict[str, RerankerInfo] = { - # ... 现有配置 ... - - "vllm/BAAI/bge-reranker-v2-m3": RerankerInfo( - name="BAAI/bge-reranker-v2-m3", - base_url="http://localhost:8000/v1/rerank", - api_key="no_api_key", - ), -} -``` - -#### 2. 动态配置（可选） - -你也可以通过代码动态添加本地模型： - -```python -from src.config import config -from src.config.static.models import EmbedModelInfo, RerankerInfo - -# 添加本地嵌入模型 -config.embed_model_names["local/embed-model"] = EmbedModelInfo( - name="local-embed-model", - dimension=1024, - base_url="http://localhost:8000/v1/embeddings", - api_key="no_api_key", -) - -# 添加本地重排序模型 -config.reranker_names["local/reranker-model"] = RerankerInfo( - name="local-reranker-model", - base_url="http://localhost:8000/v1/rerank", - api_key="no_api_key", -) - -# 保存配置 -config.save() -``` - -#### 2. 启动模型服务 - -```bash -# 启动嵌入模型 -vllm serve Qwen/Qwen3-Embedding-0.6B \ - --task embed \ - --dtype auto \ - --port 8000 - -# 启动重排序模型 -vllm serve BAAI/bge-reranker-v2-m3 \ - --task score \ - --dtype fp16 \ - --port 8000 -``` \ No newline at end of file diff --git a/docs/v0.3.0/intro/project-overview.md b/docs/v0.3.0/intro/project-overview.md deleted file mode 100644 index 7390fe1f..00000000 --- a/docs/v0.3.0/intro/project-overview.md +++ /dev/null @@ -1,37 +0,0 @@ -# 项目简介 - -Yuxi-Know（语析）是一个基于知识图谱和向量数据库的智能知识库系统，融合了 RAG（检索增强生成）技术与知识图谱技术，为用户提供智能问答和知识管理服务。 - -特点是技术栈简单，易于上手，使用 MIT 开源协议，非常适合二次开发使用。 - -### 技术栈选择 - -- **后端服务**: [FastAPI](https://github.com/tiangolo/fastapi) + Python 3.12+ -- **前端界面**: [Vue.js 3](https://github.com/vuejs/vue) + [Ant Design Vue](https://github.com/vueComponent/ant-design-vue) -- **数据库存储**: [SQLite](https://github.com/sqlite/sqlite) + [MinIO](https://github.com/minio/minio) -- **知识存储**: [Milvus](https://github.com/milvus-io/milvus)、[Chroma](https://github.com/chroma-core/chroma)（向量数据库）+ [Neo4j](https://github.com/neo4j/neo4j)（图数据库） -- **智能体框架**: [LangGraph](https://github.com/langchain-ai/langgraph) -- **文档解析**: [LightRAG](https://github.com/HKUDS/LightRAG) + [MinerU](https://github.com/HKUDS/MinerU) + [PP-Structure-V3](https://github.com/PaddlePaddle/PaddleOCR) -- **容器编排**: [Docker Compose](https://github.com/docker/compose) - -### 核心功能 - -- **智能问答**: 支持多种大语言模型，提供智能对话和问答服务 -- **知识库管理**: 支持多种存储形式（Chroma、Milvus、LightRAG） -- **知识图谱**: 自动构建和可视化知识图谱，支持图查询 -- **文档解析**: 支持 PDF、Word、图片等多种格式的智能解析 -- **权限管理**: 三级权限体系（超级管理员、管理员、普通用户） -- **内容安全**: 内置内容审查机制，保障服务合规性 - -## 演示视频 - -

\ No newline at end of file diff --git a/docs/v0.3.0/intro/quick-start.md b/docs/v0.3.0/intro/quick-start.md deleted file mode 100644 index efe8db2b..00000000 --- a/docs/v0.3.0/intro/quick-start.md +++ /dev/null @@ -1,135 +0,0 @@ -# 快速开始指南 - -::: tip 提示 -除了此文档网站外，小伙伴们还可以在 [Zread](https://zread.ai/xerrors/Yuxi-Know) 或 [DeepWiki](https://deepwiki.com/xerrors/Yuxi-Know) 平台查看自动生成的详细项目文档。 -::: - - -## 快速开始 - - -### 安装步骤 - -项目采用微服务架构，核心服务无需 GPU 支持。GPU 仅用于可选的 OCR 服务和本地模型推理，可通过环境变量配置外部服务。 - -#### 1. 获取项目代码 - -```bash -# 克隆稳定版本 -git clone --branch v0.3.0 --depth 1 https://github.com/xerrors/Yuxi-Know.git -cd Yuxi-Know -``` - -::: warning 版本说明 -- `v0.3.0`: 稳定版本 -- `v0.3.0`：最新的 Beta 测试版 -- `main`: 最新开发版本（不稳定，新特性可能会导致新 bug） -::: - -#### 2. 配置环境变量 - -复制环境变量模板并编辑： - -```bash -cp .env.template .env -``` - -编辑 `.env` 文件，配置必需的 API 密钥： - - -<<< @/../.env.template#model_provider{bash 2} - - -::: tip 免费获取 API Key -[硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) 注册即送 14 元额度，支持多种开源模型。 -::: - -#### 3. 启动服务 - -```bash -# 构建并启动所有服务 -docker compose up --build - -# 后台运行（推荐） -docker compose up --build -d -``` - -#### 4. 访问系统 - -服务启动完成后，访问以下地址： - -- **Web 界面**: `http://localhost:5173` -- **API 文档**: `http://localhost:5050/docs` - -#### 5. 停止服务 - -```bash -docker compose down -``` - -### 故障排除 - -#### 查看服务状态 - -```bash -# 查看所有容器状态 -docker ps - -# 查看后端服务日志 -docker logs api-dev -f - -# 查看前端服务日志 -docker logs web-dev -f -``` - -#### 常见问题 - -
-Docker 镜像拉取失败 - -如果拉取镜像失败，可以尝试手动拉取： - -```bash -bash docker/pull_image.sh python:3.11-slim -``` - -**离线部署方案**： - -```bash -# 在有网络的环境保存镜像 -bash docker/save_docker_images.sh # Linux/macOS -powershell -ExecutionPolicy Bypass -File docker/save_docker_images.ps1 # Windows - -# 传输到目标设备 -scp docker_images_xxx.tar @: - -# 在目标设备加载镜像 -docker load -i docker_images_xxx.tar -``` - -
- -
-构建失败 - -如果构建失败，通常是网络问题，可以配置代理： - -```bash -export HTTP_PROXY=http://IP:PORT -export HTTPS_PROXY=http://IP:PORT -``` - -如果已配置代理但构建失败，尝试移除代理后重试。 - -
- -
-Milvus 启动失败 - -```bash -# 重启 Milvus 服务 -docker compose up milvus -d -docker restart api-dev -``` - -
diff --git a/web/src/components/ToolCallingResult/BaseToolCall.vue b/web/src/components/ToolCallingResult/BaseToolCall.vue index 3aff665b..8f377ee9 100644 --- a/web/src/components/ToolCallingResult/BaseToolCall.vue +++ b/web/src/components/ToolCallingResult/BaseToolCall.vue @@ -290,7 +290,6 @@ const formatResultData = (data) => { flex-shrink: 0; } - :deep(span.code) { font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace; }