diff --git a/README.md b/README.md index 7fc0854d..bbd5d166 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@
Yuxi-Know | Trendshift -[![Stable](https://img.shields.io/badge/stable-v0.3.0-blue.svg)](https://github.com/xerrors/Yuxi-Know/tree/v0.3.0) +[![Stable](https://img.shields.io/badge/stable-v0.4.0-blue.svg)](https://github.com/xerrors/Yuxi-Know/tree/v0.4.0) [![](https://img.shields.io/badge/Docker-2496ED?style=flat&logo=docker&logoColor=ffffff)](https://github.com/xerrors/Yuxi-Know/blob/main/docker-compose.yml) [![](https://img.shields.io/github/issues/xerrors/Yuxi-Know?color=F48D73)](https://github.com/xerrors/Yuxi-Know/issues) [![License](https://img.shields.io/github/license/bitcookies/winrar-keygen.svg?logo=github)](https://github.com/xerrors/Yuxi-Know/blob/main/LICENSE) @@ -14,7 +14,7 @@
-📄 [**文档中心**](https://xerrors.github.io/Yuxi-Know/) | +📄 [**文档中心**](https://xerrors.github.io/Yuxi-Know/) | 📽️ [**视频演示**](https://www.bilibili.com/video/BV1DF14BTETq/)
@@ -35,8 +35,8 @@ - **[2025/12/17] v0.4.0-beta 版本发布**
查看详细更新日志 - - + + ### 新增 - 新增对于上传附件的智能体中间件，详见[文档](https://xerrors.github.io/Yuxi-Know/latest/advanced/agents-config.html#%E6%96%87%E4%BB%B6%E4%B8%8A%E4%BC%A0%E4%B8%AD%E9%97%B4%E4%BB%B6) - 新增多模态模型支持（当前仅支持图片），详见[文档](https://xerrors.github.io/Yuxi-Know/latest/advanced/agents-config.html#%E5%A4%9A%E6%A8%A1%E6%80%81%E5%9B%BE%E7%89%87%E6%94%AF%E6%8C%81) @@ -53,15 +53,15 @@ - 优化图谱可视化方式，统一图谱数据结构，统一使用基于 G6 的可视化方式，同时支持上传带属性的图谱文件，详见[文档](https://xerrors.github.io/Yuxi-Know/latest/intro/knowledge-base.html#_1-%E4%BB%A5%E4%B8%89%E5%85%83%E7%BB%84%E5%BD%A2%E5%BC%8F%E5%AF%BC%E5%85%A5) - 优化 DBManager / ConversationManager，支持异步操作 - 优化 知识库详情页面，更加简洁清晰，增强文件下载功能 - + ### 修复 - 修复重排序模型实际未生效的问题 - 修复消息中断后消息消失的问题，并改善异常效果 - 修复当前版本如果调用结果为空的时候，工具调用状态会一直处于调用状态，尽管调用是成功的 - 修复检索配置实际未生效的问题 - + ### 破坏性更新 - + - 移除 Chroma 的支持，当前版本标记为移除 - 移除模型配置预设的 TogetherAI
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 62f6d259..3cbfac57 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -58,35 +58,29 @@ export default defineConfig({ ] } ], - '/v0.3.0/': [ + '/v0.4.0/': [ { text: '简介', items: [ - { text: '什么是 Yuxi-Know？', link: '/v0.3.0/intro/project-overview' }, - { text: '快速开始', link: '/v0.3.0/intro/quick-start' }, - { text: '模型配置', link: '/v0.3.0/intro/model-config' }, - { text: '知识库与知识图谱', link: '/v0.3.0/intro/knowledge-base' } + { text: '什么是 Yuxi-Know？', link: '/v0.4.0/intro/project-overview' }, + { text: '快速开始', link: '/v0.4.0/intro/quick-start' }, + { text: '模型配置', link: '/v0.4.0/intro/model-config' }, + { text: '知识库与知识图谱', link: '/v0.4.0/intro/knowledge-base' }, + { text: '知识库评估', link: '/v0.4.0/intro/evaluation' } ] }, { text: '高级配置', items: [ - { text: '配置系统详解', link: '/v0.3.0/advanced/configuration' }, - { text: '文档解析', link: '/v0.3.0/advanced/document-processing' }, - { text: '智能体', link: '/v0.3.0/advanced/agents-config' }, - { text: '品牌自定义', link: '/v0.3.0/advanced/branding' }, - { text: '其他配置', link: '/v0.3.0/advanced/misc' } - ] - }, - { - text: '更新日志', - items: [ - { text: '版本说明 v0.3', link: '/v0.3.0/changelog/0.3-release-notes' }, - { text: '参与贡献', link: '/v0.3.0/changelog/contributing' }, - { text: '常见问题', link: '/v0.3.0/changelog/faq' } + { text: '配置系统详解', link: '/v0.4.0/advanced/configuration' }, + { text: '文档解析', link: '/v0.4.0/advanced/document-processing' }, + { text: '智能体', link: '/v0.4.0/advanced/agents-config' }, + { text: '品牌自定义', link: '/v0.4.0/advanced/branding' }, + { text: '其他配置', link: '/v0.4.0/advanced/misc' }, + { text: '生产部署', link: '/v0.4.0/advanced/deployment' } ] } - ] + ], }, socialLinks: [ diff --git a/docs/index.md b/docs/index.md index 410e1c7d..4ee6b3c7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,8 +14,8 @@ hero: text: Latest 文档 link: /latest/intro/quick-start - theme: alt - text: v0.3.0 文档 - link: /v0.3.0/intro/quick-start + text: v0.4.0 文档 + link: /v0.4.0/intro/quick-start features: - title: 🤖 智能体与模型 diff --git a/docs/public/bb.png b/docs/public/bb.png index 71350bc9..d79b9d42 100644 Binary files a/docs/public/bb.png and b/docs/public/bb.png differ diff --git a/docs/v0.4.0/advanced/agents-config.md b/docs/v0.4.0/advanced/agents-config.md new file mode 100644 index 00000000..ccc44177 --- /dev/null +++ b/docs/v0.4.0/advanced/agents-config.md @@ -0,0 +1,276 @@ +# 智能体 + +## 智能体开发 + +系统基于 [LangGraph](https://github.com/langchain-ai/langgraph) 并通过统一的 `AgentManager` 管理所有智能体。`src/agents/__init__.py` 会在启动时遍历 `src/agents` 目录，对每个包含 `__init__.py` 的子包执行自动发现：所有继承 `BaseAgent` 的类都会被注册并立即初始化，因此只要代码落位正确，就不需要再手动登记或修改管理器。 + +仓库预置了若干可直接运行的智能体：`chatbot` 聚焦对话与动态工具调度，`mini_agent` 提供精简模板，`reporter` 演示报告类链路。这些目录展示了上下文类、Graph 构造方式、子智能体引用以及中间件组合的范例，新增功能时可以直接复用。 + +### 智能体元数据配置 + +每个智能体可以通过在智能体目录下创建 `metadata.toml` 文件来配置元数据信息。这个文件使用 TOML 格式，包含以下字段： + +- `name`: 智能体显示名称 +- `description`: 智能体功能描述 +- `examples`: 示例问题列表（数组格式） + +例如，`src/agents/chatbot/metadata.toml`： + +<<< @/../src/agents/chatbot/metadata.toml + +**注意**：`metadata.toml` 文件是可选的，如果没有提供，系统将使用智能体类的基本属性。 + +### 创建新的智能体 + +在 `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` 列表中引用。 + +#### 文件上传中间件 + +文件上传功能通过 `inject_attachment_context` 中间件实现（位于 `src/agents/common/middlewares/attachment_middleware.py`）。该中间件基于 LangChain 1.0 的 `AgentMiddleware` 标准实现，具有以下特点： + +1. **状态扩展**：定义 `AttachmentState` 扩展 `AgentState`，添加可选的 `attachments` 字段 +2. **自动注入**：在模型调用前，从 `request.state` 中读取附件并转换为 `SystemMessage` +3. **向后兼容**：不使用文件上传的智能体不受影响 + +##### 为智能体启用文件上传 + +只需两步： + +**步骤 1：声明能力**（让前端显示上传按钮） + +```python +class MyAgent(BaseAgent): + capabilities = ["file_upload"] +``` + +**步骤 2：添加中间件**（让智能体能够处理附件内容） + +```python +from src.agents.common.middlewares import inject_attachment_context + +async def get_graph(self): + graph = create_agent( + model=load_chat_model("..."), + tools=get_tools(), + middleware=[ + inject_attachment_context, # 添加附件中间件 + context_aware_prompt, # 其他中间件... + # ... + ], + checkpointer=await self._get_checkpointer(), + ) + return graph +``` + +##### 工作流程 + +1. **前端上传**：用户在聊天界面上传文档（txt、md、docx、html） +2. **API 解析**：后端将文档转换为 Markdown 格式并存储到数据库（超过 32k 会被截断） +3. **自动加载**：API 层在调用 agent 前从数据库加载附件数据 +4. **中间件注入**：`inject_attachment_context` 自动将附件内容注入为系统消息 +5. **模型处理**：LLM 接收到附件内容和用户问题，进行综合回答 + +这种设计确保了附件功能的可选性和可扩展性，任何智能体都可以通过添加中间件快速启用文件上传能力。 + +## 内置工具与 MCP 集成 + +系统会根据配置自动组装工具集合，涵盖知识图谱查询、向量检索生成的动态工具、MySQL 只读查询能力、Tavily 搜索以及所有注册的 MCP 工具。 + +工具的启用状态和描述由配置文件或环境变量决定，当依赖缺失时会被中间件自动忽略，从而避免在图中加载不可用能力。MCP Server 的接入方式保持不变，只需在 `src/agents/common/mcp.py` 的 `MCP_SERVERS` 中填入服务地址与 `transport` 类型，如需更多范式可参阅 LangChain 官方文档。 + +### MCP 服务器配置方式 + +系统支持四种 MCP 服务器配置方式，可根据具体场景选择： + +#### 1. 远程 HTTP 服务器 + +```python +MCP_SERVERS = { + "sequentialthinking": { + "url": "https://remote.mcpservers.org/sequentialthinking/mcp", + "transport": "streamable_http", + } +} +``` + +**特点**： +- 通过 HTTP 远程访问，无需本地安装，适合公开可用的 MCP 服务 +- 启动速度快，无需本地依赖 + +#### 2. 使用 npx 运行 Node.js 包 + +```python +MCP_SERVERS = { + "mcp-server-chart": { + "command": "npx", + "args": ["-y", "@antv/mcp-server-chart"], + "transport": "stdio" + }, +} +``` + +**特点**： +- 使用 npx 直接运行 Node.js 包，`-y` 参数自动下载并运行指定包 +- 适合 Node.js 生态的 MCP 服务，需要确保 npx 可以使用 + +#### 3. 使用 uvx 运行 Python 包 + +```python +MCP_SERVERS = { + "mysql-mcp-server": { + "command": "uvx", + "args": ["mysql_mcp_server"], + "env": { + "MYSQL_DATABASE": "your_database", + "MYSQL_HOST": "localhost", + "MYSQL_PASSWORD": "your_password", + "MYSQL_PORT": "3306", + "MYSQL_USER": "your_username" + }, + "transport": "stdio" + } +} +``` + +**特点**： +- 使用 uvx 运行已发布的 Python 包，自动管理虚拟环境和依赖 +- 适合 PyPI 上已发布的 MCP 服务 + +#### 4. 使用 uv 运行本地仓库 + +```python +MCP_SERVERS = { + "arxiv-mcp-server": { + "command": "uv", + "args": [ + "tool", + "run", + "arxiv-mcp-server", + "--storage-path", "src/agents/mcp_repos/arxiv-mcp-server" + ], + "transport": "stdio" + } +} +``` + +**特点**： +- 直接运行本地 git 仓库中的 MCP 服务 +- 加载速度快，支持热重载，适合开发调试和自定义 MCP 服务 +- 需要先 git clone 对应仓库到指定路径 + +### 配置参数说明 + +- `url`: 远程 HTTP 服务器的 URL（仅 streamable_http 传输） +- `command`: 启动 MCP 服务的命令 +- `args`: 启动参数列表 +- `env`: 环境变量配置，用于数据库连接等敏感信息 +- `transport`: 传输协议，支持 `stdio`（本地）和 `streamable_http`（远程） + +### 动态工具加载 + +系统支持动态加载 MCP 工具： + +```python +from src.agents.common.mcp import get_mcp_tools, add_mcp_server + +# 获取特定服务器的工具 +tools = await get_mcp_tools("sequentialthinking") + +# 动态添加新的 MCP 服务器 +add_mcp_server("custom-server", { + "url": "https://your-mcp-server.com/mcp", + "transport": "streamable_http" +}) + +# 获取所有 MCP 工具 +all_tools = await get_all_mcp_tools() +``` +### MySQL 数据库 + +在 数据库报表助手（SqlReporterAgent） 中，可以通过配置下面环境变量，让 Agent 能够连接到 MySQL 数据库。并通过执行 SQL 查询，获取数据库中的数据。 + +设置数据库连接时，在 `.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，智能体可以自动陈述数据库用途并选择更准确的检索策略。详见代码部分 `src/agents/common/toolkits/mysql/` + +### 多模态图片支持 + +系统支持接收图片作为输入，与文本结合形成多模态查询。图片支持的核心特性如下： + +#### 1. 图片上传与处理 +- 通过 `/chat/image/upload` 接口上传图片 +- 自动处理图片格式转换和压缩 +- 返回 base64 编码的图片数据 +- 图片大小限制为 10MB +- 支持的图片格式：JPEG、PNG、WebP、GIF、BMP +- 自动压缩超过 5MB 的图片 + +当发送包含图片的请求时，消息格式为： +```json +{ + "query": "这张图片里有什么？", + "image_content": "", + "config": {}, + "meta": {} +} +``` + +智能体会自动识别多模态消息并将其传递给支持图片的模型。如果模型不支持图片，会自动忽略图片内容，只处理文本部分。系统会将图片转换为符合模型要求的格式（通常是 base64 编码的 JPEG 或 PNG），确保与主流多模态模型兼容。 + +目前仅支持上传单个图片，图片以 base64 编码形式存储在数据库。系统会自动处理图片的格式转换和压缩，并生成缩略图以优化性能。 + +### 图片上传响应格式 + +```json +{ + "success": true, + "image_content": "", + "thumbnail_content": "", + "width": 1024, + "height": 768, + "format": "JPEG", + "mime_type": "image/jpeg" +} +``` + +系统会将图片信息与用户查询一同传递给支持多模态的模型，并自动适配模型要求的格式。 diff --git a/docs/v0.4.0/advanced/branding.md b/docs/v0.4.0/advanced/branding.md new file mode 100644 index 00000000..6a841cfc --- /dev/null +++ b/docs/v0.4.0/advanced/branding.md @@ -0,0 +1,60 @@ +# 品牌自定义 + +系统支持完整的品牌信息自定义，包括 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 + +上述中提到的 ICON 预设了下面这些，如果需要更多的 ICONS，可以手动从 `lucide-vue-next` 中引入。 + +<<< @/../web/src/views/HomeView.vue#icon_mapping{js} + +### 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-1000: #f0f2f5; /* 色板 */ + --main-900: #e6f7ff; /* 色板 */ + /* ... 其他色板 */ +} + +``` + +**此外**，`web/src/stores/theme.js` 中也包含了主题相关的配置（需要修改 `colorPrimary`），可根据需要修改。 + +## 修改首页 + +首页提供了一个插槽组件 `web/src/components/ProjectOverview.vue`，可以在该组件中自定义项目介绍，当前为空文件。（借助 AI 编程可以设计出更好看的首页的） diff --git a/docs/v0.4.0/advanced/configuration.md b/docs/v0.4.0/advanced/configuration.md new file mode 100644 index 00000000..456fdb77 --- /dev/null +++ b/docs/v0.4.0/advanced/configuration.md @@ -0,0 +1,185 @@ +# 配置系统详解 + +## 概述 + +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") + 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", + env="SILICONFLOW_API_KEY", + models=[ + "deepseek-ai/DeepSeek-V3.2", + "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", + "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.4.0/advanced/deployment.md b/docs/v0.4.0/advanced/deployment.md new file mode 100644 index 00000000..c3868d4b --- /dev/null +++ b/docs/v0.4.0/advanced/deployment.md @@ -0,0 +1,69 @@ +# 生产部署指南 + +本指南介绍了如何在生产环境中部署 Yuxi-Know。 + +## 前置要求 + +- **Docker Engine** (v24.0+) +- **Docker Compose** (v2.20+) +- **NVIDIA Container Toolkit** (如果在生产环境使用 GPU 服务) + +注意事项： + +1. 生产环境和开发环境最好是两台独立的机器，不然会存在端口和资源的冲突问题。 +2. 虽然名为“生产环境”，但实际上只是做了一些基本的配置而已，真要上线业务，需要根据实际情况进行调整。 + +## 部署步骤 + +### 1. 配置环境变量 + +为了避免与开发环境的冲突，建议在生产环境中使用 `.env.prod` 文件。请确保你已经从模板创建了该文件并填写了必要的密钥。 + +```bash +cp .env.template .env.prod +``` + +编辑 `.env.prod` 文件，设置强密码并配置必要的 API 密钥： + +- `NEO4J_PASSWORD`: 修改默认密码 +- `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`: 修改默认密钥 +- `SILICONFLOW_API_KEY` 等模型密钥 + +### 2. 启动服务 + +使用 `docker-compose.prod.yml` 文件启动生产环境： + +```bash +# 仅启动核心服务 (CPU 模式) +docker compose -f docker-compose.prod.yml up -d --build + +# 启动所有服务 (包含 GPU OCR 服务) +docker compose -f docker-compose.prod.yml --profile all up -d --build +``` + +### 3. 验证部署 + +- **Web 访问**: `http://localhost` (直接通过 80 端口访问，无需 :5173) +- **API 健康检查**: `curl http://localhost/api/system/health` + +## 维护与更新 + +### 更新代码并重新部署 + +```bash +# 拉取最新代码 +git pull + +# 重新构建并启动 +docker compose -f docker-compose.prod.yml up -d --build +``` + +### 查看日志 + +```bash +# 查看 API 日志 +docker logs -f api-prod + +# 查看 Nginx 访问日志 +docker logs -f web-prod +``` diff --git a/docs/v0.4.0/advanced/document-processing.md b/docs/v0.4.0/advanced/document-processing.md new file mode 100644 index 00000000..3fb3e7df --- /dev/null +++ b/docs/v0.4.0/advanced/document-processing.md @@ -0,0 +1,120 @@ +# 文档处理与 OCR + +系统提供 4 种文档处理选项： + +- **RapidOCR**: CPU 友好，无需 GPU，适合基础文字识别 +- **MinerU**: 本地化高精度 VLM 解析，适合复杂 PDF 和表格文档 +- **MinerU Official**: 官方云服务 API，无需本地部署，开箱即用 +- **PaddleX**: 结构化解析，适合表格、票据等特殊格式 + +## 支持的文件类型 + +### 常规文档格式 +- **文本文档**: `.txt`, `.md`, `.html`, `.htm` +- **Word 文档**: `.docx` +- **PDF 文档**: `.pdf` +- **电子表格**: `.csv`, `.xls`, `.xlsx` +- **JSON 数据**: `.json` + +### 图像格式（需要 OCR） +- **常见图片**: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tiff`, `.tif`, `.gif`, `.webp` + +### ZIP 压缩包 +- **ZIP 文档**: `.zip` - 支持包含 Markdown 文件和图片的压缩包 + - 自动提取和处理 ZIP 包中的 `.md` 文件 + - 自动处理 ZIP 包中的图片文件并上传到对象存储（MINIO） + - 图片链接会自动替换为可访问的 URL + - 优先处理名为 `full.md` 的文件，否则使用第一个 `.md` 文件 + - 支持图片目录的智能识别（`images/`、`../images/` 等） + +::: tip 图片显示 +文档中的图片会自动上传到对象存储并替换为可访问的 URL。但是如果想要在外部正常显示图片，需要配置 `HOST_IP` 环境变量，将其设置为您的服务器 IP 地址。 +::: + +## 快速配置 + +### 1. 基础 OCR (RapidOCR) + +```bash +# 下载模型 +hf download SWHL/RapidOCR --local-dir ./models/SWHL/RapidOCR + +# 启动服务 +docker compose up -d api +``` + +需要确保 `MODEL_DIR` 环境变量指向 RapidOCR 上层目录，例如 `./models`。 + +### 2. 高精度 OCR (MinerU) + +需要在 `.env` 文件中配置： + +```bash +MINERU_VL_SERVER=http://localhost:30000 # 对应 docker compose 中的 mineru-vllm-server 服务 +MINERU_API_URI=http://localhost:30001 # 对应 docker compose 中的 mineru-api 服务 +``` + +然后启动相关服务 + +```bash +# 需要 GPU，启动 MinerU 服务 +docker compose up mineru-vllm-server mineru-api -d + +# 启动主服务 +docker compose up api -d +``` + +::: tip 处理超时 +文档解析超时时间默认 600 秒，可通过 `MINERU_TIMEOUT` 环境变量调整。 +::: + + +### 3. 官方云服务 (MinerU Official) + +API 密钥可以从 [MinerU 官网](https://mineru.net) 申请。 + +然后在 `.env` 文件中添加 + +```bash +# 设置 API 密钥环境变量 +MINERU_API_KEY="your-api-key-here" +``` + +然后使用 `docker compose up api -d` 重启后端服务。 + +### 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 选项 + +对应网页中的 `使用 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 环境和基础识别需求 diff --git a/docs/v0.4.0/advanced/misc.md b/docs/v0.4.0/advanced/misc.md new file mode 100644 index 00000000..3872da1a --- /dev/null +++ b/docs/v0.4.0/advanced/misc.md @@ -0,0 +1,53 @@ +# 其他配置 + +## 内容安全 + +系统内置内容审查机制（默认是关闭状态），保障服务内容的合规性。目前配置了关键词过滤以及 LLM 对内容进行审查。管理员可在 `设置` → `基本设置` 页面中进行配置并选择安全模型。 + +检测流程为，接收到用户输入之后，就对用户的输入进行检测是否合规，同时在流式传输的过程中进行实时检测（仅关键词）。当流式输出结束之后，则开始检测整个内容。 +**注意**，使用 LLM 检测虽然可以大大缓解提示词注入带来的问题，但也会在用户交互上带来延迟影响，需要考虑是否启用。 + +对于关键词检测，敏感词词库位于 `src/config/static/bad_keywords.txt` 文件，每行一个关键词，实时生效，无需重启服务。 + +对于 LLM 检测，Prompt 可以看到 `src/plugins/guard.py`： + +<<< @/../src/plugins/guard.py#guard_prompt + +## 网页搜索 + +系统内置了基于 Tavily 的联网搜索能力，配置完成后，大模型会自动在需要时调用对应的工具，为回答提供实时网页信息。 + + +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` 即可。 + +完成以上步骤后，在智能体的工具配置区域即可看到这个工具，展示 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.4.0/intro/evaluation.md b/docs/v0.4.0/intro/evaluation.md new file mode 100644 index 00000000..fa7e3850 --- /dev/null +++ b/docs/v0.4.0/intro/evaluation.md @@ -0,0 +1,57 @@ +# 知识库评估使用与开发指南 + +知识库评估功能用于测试 RAG 系统的检索和生成质量。通过预设的测试问题和标准答案（或自动生成评估），量化评估系统在不同场景下的表现。 + +**适用场景**：验证知识库上线前的效果、对比不同配置下的检索效果、定期监控知识库质量变化、调优检索参数。 + +**注意**：当前版本支持 Milvus 类型的知识库。 + +## 如何创建评估基准 + +### 1. 上传评估文件 + +准备 JSONL 格式的文件，每行一个测试样本： + +```json +{"query": "什么是人工智能？", "gold_chunk_ids": ["chunk_001", "chunk_002"], "gold_answer": "人工智能是计算机科学的一个分支"} +{"query": "机器学习的主要类型有哪些？", "gold_chunk_ids": ["chunk_005"], "gold_answer": "主要包括监督学习、无监督学习和强化学习"} +{"query": "深度学习的应用领域", "gold_chunk_ids": ["chunk_010", "chunk_011"]} +``` + +**字段说明**： +- `query`（必需）：测试问题，用于触发 RAG 系统的检索 +- `gold_chunk_ids`（可选）：相关文档块的 ID 列表，用于验证检索效果 +- `gold_answer`（可选）：标准答案，用于验证生成效果 + +::: tip 数据集构建 +可以使用 [EasyDataset](https://github.com/ConardLi/easy-dataset) 从文档批量生成问答对、可视化编辑、导出多种格式和数据质量检查。挺好用的，推荐。注意导出的时候的字段需要修改为 `query`、`gold_answer`。 +::: + + +### 2. 自动生成评估基准 + +Yuxi 也实现了一个简易的、可以基于现有知识库自动生成测试数据。流程是：随机采样一个 chunk → 用嵌入模型找相似 chunk → 用 LLM 生成问题和答案。 + +**推荐参数设置**： +- 问题数量：10-50 个 +- 相似文档数：每个问题 2-5 个 + +## 运行评估任务 + +1. 选择评估基准后在知识库页面点击"评估"标签 + +2. 配置参数： + - **答案生成模型（可选）**：如果选择了，则会基于检索的 chunk 生成答案，然后用评判模型评估答案的准确性 + - **评判模型（可选）**：如果选择了，则会用评判模型评估答案的准确性，判断是否与标准答案一致，因此选择评判模型时，必须选择答案生成模型。 + +3. 点击"开始评估"： +系统会逐个处理测试问题，执行检索和生成，计算各项指标。评估在后台运行，可以继续其他操作。 + +**主要指标**： + +| 指标 | 含义 | 如何看待 | +|------|------|----------| +| Recall@1 | 第一个结果包含正确文档的比例 | 最重要的指标，反映用户第一眼看到的准确率 | +| Recall@5 | 前5个结果包含正确文档的比例 | 综合检索效果，应该大于 0.8 | +| F1@K | 精确率和召回率的调和平均 | 平衡指标，用于对比不同配置 | +| 答案准确性 | 生成答案是否与标准答案一致 | 检查 LLM 理解和表达能力 | diff --git a/docs/v0.4.0/intro/knowledge-base.md b/docs/v0.4.0/intro/knowledge-base.md new file mode 100644 index 00000000..08f67003 --- /dev/null +++ b/docs/v0.4.0/intro/knowledge-base.md @@ -0,0 +1,117 @@ +# 知识库与知识图谱 + +项目中的知识库与知识图谱，即是知识管理组织的方式，同时会被封装为工具供 AgenticRAG 系统调用。 + +## 创建知识库 + +系统支持多种知识库存储形式，满足不同场景需求： + +| 存储类型 | 特点 | 适用场景 | +|----------|------|----------| +| **Chroma** | 轻量级向量数据库 | 已弃用，建议使用 Milvus | +| **Milvus** | 高性能向量数据库 | 大规模生产环境、高性能查询 | +| **LightRAG** | 图增强检索 | 复杂知识关系，构建成本较高 | + +访问 Web 界面：`http://localhost:5173`，进入"知识库管理"页面，点击"新建知识库"，填写知识库信息。 + +这里需要**注意**的是，这里的知识库的标题和描述都会作为智能体选择工具的依据，因此尽量详尽的描述该知识库。 + + +### LightRAG 知识库说明 + +在本项目中，系统支持基于 [LightRAG](https://github.com/HKUDS/LightRAG) 的知识图谱自动构建，能够从文档中自动提取实体和关系，构建结构化知识图谱。 + +**LightRAG 图谱 vs 全局知识图谱的区别：** + +- **LightRAG 图谱**（知识库专属）：针对单个知识库由 LightRAG 自动抽取实体/关系，用于该库内的图增强检索与可视化。通过特殊的 label（知识库ID）与全局图谱区分，不会混入全局数据。 + +- **全局知识图谱**（系统级）：通过三元组文件上传的图谱数据，提供系统级的知识图谱查询和可视化能力，会作为工具供 LLM 使用。 + +两者共享同一个 Neo4j 实例，但完全隔离，互不影响。 + +LightRAG 知识库可在知识库详情、知识图谱中可视化。由于免费版的 neo4j 智能创建一个图数据库，因此实际上 LightRAG 的节点和边依然是和知识图谱本身构建在了同一个 Neo4j 数据库中，但是使用了特殊的 label `{知识库ID}` 做区分。 + +同时项目支持原 LightRAG 的所有环境变量，只需要在项目的 `.env` 文件中配置即可。比如当本地计算资源有限时，可以配置 `EMBEDDING_TIMEOUT=60`, `LLM_TIMEOUT=180` 增加超时时间。 + +## 文档管理 + +本系统的“上传 → 解析入库 → 检索/可视化”流程既可通过 Web 界面完成，也可使用 API/脚本批量处理。详见[文档解析](../advanced/document-processing.md) + +接口查询：`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`，可在任务中心查看进度 + +去重策略：系统按“内容哈希”判断是否已存在相同文件，避免重复入库。 + +## 知识图谱 + +本项目存在两类“图谱相关”能力： + +- 上传的知识图谱（Neo4j）：提供三元组检索和系统级可视化。会作为工具供 LLM 使用。 +- LightRAG 知识库内图谱：针对某个知识库由 LightRAG 自动抽取实体/关系，用于该库内的图增强检索与可视化；与上传的图谱共享同一 Neo4j 实例，但通过特殊 label 区分，不作为全局图谱使用。 + + +### 1. 以三元组形式导入 + +系统支持通过网页导入 `jsonl` 格式的知识图谱数据，支持**简单三元组**和**带属性三元组**两种格式。 + +**简单格式（兼容旧版）**： + +```jsonl +{"h": "北京", "t": "中国", "r": "首都"} +{"h": "上海", "t": "中国", "r": "直辖市"} +``` + +**扩展格式（支持属性）**： + +支持 `h`（头节点）、`t`（尾节点）和 `r`（关系）为对象结构，其中： +- 节点对象必须包含 `name` 字段。 +- 关系对象必须包含 `type` 字段。 +- 其他字段将作为**属性**存储在 Neo4j 中。 + +```jsonl +{"h": {"name": "孙悟空", "title": "齐天大圣", "weapon": "如意金箍棒"}, "t": {"name": "唐僧", "species": "人"}, "r": {"type": "徒弟", "order": 1}} +{"h": "猪八戒", "t": {"name": "唐僧"}, "r": {"type": "徒弟", "order": 2}} +``` + +**格式说明**： +- 每行一个数据项。 +- 系统自动验证数据格式，并自动导入到 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` +- 扩展属性格式：`test/data/complex_graph_test.jsonl` +::: + +### 2. 接入已有 Neo4j 实例 + +如需接入已有的 Neo4j 实例，可修改 `.env` 中的配置： + +<<< @/../.env.template#neo4j{bash} + +同时记得注释掉下面的 neo4j 服务： + +<<< @/../docker-compose.yml#neo4j + + +::: warning 注意事项 +确保每个节点都有 `Entity` 标签，每个关系都有 `RELATION` 类型，否则会影响图的检索与构建功能。 +::: diff --git a/docs/v0.4.0/intro/model-config.md b/docs/v0.4.0/intro/model-config.md new file mode 100644 index 00000000..b7afba61 --- /dev/null +++ b/docs/v0.4.0/intro/model-config.md @@ -0,0 +1,227 @@ +# 模型配置 + +## 对话模型 + +系统支持多种大语言模型服务商，通过配置对应的 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` 文件中添加对应的环境变量： + + + +::: tip 免费获取 API Key +[硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) 注册即送 14 元额度，支持多种开源模型。 +::: + +<<< @/../.env.template#model_provider{bash 5} + +### 默认对话模型格式 + +系统的默认对话模型可以在设置页面配置，也可以通过配置项 `default_model` 指定，格式统一为 `模型提供商/模型名称`，例如： + +```yaml +default_model: siliconflow/deepseek-ai/DeepSeek-V3.2 +``` + +## 自定义模型供应商 + +::: tip 配置系统升级 (v0.3.x) +从 `v0.3.x` 版本开始，模型配置系统已升级为基于 Pydantic BaseModel 的类型安全配置，支持 TOML 格式的用户配置文件。 + +- **默认配置**: `src/config/static/models.py` (Python 代码) +- **用户配置**: `saves/config/base.toml` (TOML 格式，仅保存用户修改) +- **自定义供应商**: `saves/config/custom_providers.toml` (独立配置文件) + ::: + +系统提供了完整的自定义供应商管理功能，支持通过 Web 界面直接添加、编辑、测试和删除自定义模型供应商。 + +### 使用方法 + +系统支持任何 OpenAI 兼容的云服务提供商 + +#### 1. Web 界面操作（推荐） + +访问 **系统设置 > 模型配置**，在"自定义供应商"部分点击 **添加自定义供应商**。这里的密钥可以直接填写也可以填写对应的环境变量名称。 + +#### 2. 配置文件操作 + +如需通过配置文件管理，编辑 `saves/config/custom_providers.toml`： + +```toml +[model_names.local-vllm] +name = "本地 vLLM 服务" +url = "https://docs.vllm.ai" +base_url = "http://localhost:8000/v1" +default = "Qwen/Qwen2.5-7B-Instruct" +env = "LOCAL_VLLM_API_KEY" +models = [ + "Qwen/Qwen2.5-7B-Instruct", + "Qwen/Qwen2.5-14B-Instruct", +] +custom = true + +[model_names.local-ollama] +name = "本地 Ollama" +url = "https://ollama.com" +base_url = "http://localhost:11434/v1" +default = "llama3.2" +env = "NO_API_KEY" +models = ["llama3.2", "qwen2.5"] +custom = true +``` + +然后在 `.env` 文件中添加对应的环境变量： + +```env +LOCAL_VLLM_API_KEY=your_api_key_here +``` + +### API 端点 + +系统提供以下 API 端点管理自定义供应商： + +- `GET /api/system/custom-providers` - 获取所有自定义供应商 +- `POST /api/system/custom-providers` - 添加自定义供应商 +- `PUT /api/system/custom-providers/{provider_id}` - 更新自定义供应商 +- `DELETE /api/system/custom-providers/{provider_id}` - 删除自定义供应商 +- `POST /api/system/custom-providers/{provider_id}/test` - 测试供应商连接 + +### 常见配置示例 + +#### vLLM 本地服务 + +```toml +[model_names.vllm-local] +name = "vLLM 本地服务" +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", + "meta-llama/Llama-3.1-8B-Instruct" +] +``` + +#### Ollama 本地服务 + +```toml +[model_names.ollama-local] +name = "Ollama 本地服务" +base_url = "http://localhost:11434/v1" +default = "llama3.2" +env = "NO_API_KEY" +models = [ + "llama3.2:latest", + "qwen2.5:latest", + "codellama:latest" +] +``` + +#### 第三方 API 中转服务 + +```toml +[model_names.api-proxy] +name = "API 中转服务" +base_url = "https://api-proxy.example.com/v1" +default = "gpt-3.5-turbo" +env = "API_PROXY_KEY" +models = [ + "gpt-3.5-turbo", + "gpt-4", + "claude-3-sonnet" +] +``` + +### 故障排除 + +1. **测试连接失败**: 检查 API 地址格式和 API 密钥配置 +2. **模型不可用**: 确认模型名称拼写和服务端是否支持该模型 +3. **权限错误**: 确保用户具有管理员权限 +4. **配置未生效**: 检查环境变量配置和服务重启状态 + +## 嵌入模型和重排序模型 + +#### 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() +``` + +#### 3. 启动模型服务 + +```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 +``` diff --git a/docs/v0.4.0/intro/project-overview.md b/docs/v0.4.0/intro/project-overview.md new file mode 100644 index 00000000..494c3b17 --- /dev/null +++ b/docs/v0.4.0/intro/project-overview.md @@ -0,0 +1,24 @@ +# 项目简介 + +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、图片等多种格式的智能解析 +- **权限管理**: 三级权限体系（超级管理员、管理员、普通用户） +- **内容安全**: 内置内容审查机制，保障服务合规性 diff --git a/docs/v0.4.0/intro/quick-start.md b/docs/v0.4.0/intro/quick-start.md new file mode 100644 index 00000000..326ad268 --- /dev/null +++ b/docs/v0.4.0/intro/quick-start.md @@ -0,0 +1,178 @@ +# 快速开始指南 + +::: tip 提示 +除了此文档网站外，用户还可以在 [Zread](https://zread.ai/xerrors/Yuxi-Know) 或 [DeepWiki](https://deepwiki.com/xerrors/Yuxi-Know) 平台查看自动生成的详细项目文档。 +::: + + +## 快速开始 + + +### 安装步骤 + +项目采用微服务架构，核心服务无需 GPU 支持。GPU 仅用于可选的 OCR 服务和本地模型推理，可通过环境变量配置外部服务。 + +#### 1. 获取项目代码 + +```bash +# 克隆稳定版本 +git clone --branch v0.4.0 --depth 1 https://github.com/xerrors/Yuxi-Know.git +cd Yuxi-Know +``` + +::: warning 版本说明 +- `v0.4.0`: 稳定版本 +- `main`: 最新开发版本（不稳定，新特性可能会导致新 bug） +::: + +#### 2. 项目启动 + +**方法 1**：使用 init 脚本（推荐） + +我们提供了自动化的初始化脚本，可以帮您完成环境配置和 Docker 镜像拉取： + +```bash +# Linux/macOS +./scripts/init.sh + +# Windows PowerShell +.\scripts\init.ps1 +``` + +脚本会： +- 检查并创建 `.env` 文件 +- 提示您输入 `SILICONFLOW_API_KEY`（必需） +- 提示您输入 `TAVILY_API_KEY`（可选，用于搜索服务） +- 自动拉取所有必需的 Docker 镜像 + +::: tip API Key 获取 +- [硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) 注册即送 14 元额度 +- [Tavily](https://app.tavily.com/) 获取搜索服务 API Key（可选） +::: + +**方法 2**：手动配置环境变量 + +复制环境变量模板并编辑： + +```bash +cp .env.template .env +``` + +编辑 `.env` 文件，配置必需的 API 密钥，这里强烈建议先使用硅基流动的 API 和模型（DeepSeek）验证平台的功能无误后，再尝试切换到自己的模型： + + +<<< @/../.env.template#model_provider{bash 5} + + +::: 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 +``` + +## 对话 + +项目第一次启动后，会要求填写超级管理员账号和密码，请确保填写正确。 + +然后在智能体页面可以进行对话，在右侧可以配置提示词、模型、工具等参数。 + +![agent.png](/images/agent.png) + + + +## 故障排除 + +#### 查看服务状态 + +```bash +# 查看所有容器状态 +docker ps + +# 查看后端服务日志 +docker logs api-dev -f + +# 查看前端服务日志 +docker logs web-dev -f +``` + +#### 常见问题 + +
+Docker 镜像拉取失败 + +如果拉取镜像失败，可以尝试手动拉取： + +```bash +# Linux/macOS +bash docker/pull_image.sh python:3.12-slim + +# Windows PowerShell +powershell -ExecutionPolicy Bypass -File docker/pull_image.ps1 python:3.12-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 +# Linux / macOS +export HTTP_PROXY=http://IP:PORT +export HTTPS_PROXY=http://IP:PORT + +# Windows PowerShell +$env:HTTP_PROXY="http://IP:PORT" +$env:HTTPS_PROXY="http://IP:PORT" +``` + +如果已配置代理但构建失败，尝试移除代理后重试。 + +
+ +
+Milvus 启动失败 + +```bash +# 重启 Milvus 服务 +docker compose up milvus -d +docker restart api-dev +``` + +