refactor: 更新文档部署说明
- 移除对于双版本文档的支持，更加清晰 - 将 docs 的入口从根目录移动到子目录
This commit is contained in:
Wenjie Zhang
parent
1033b63450
commit
62bb928064
13
.github/workflows/deploy.yml
vendored
13
.github/workflows/deploy.yml
vendored
@ -32,21 +32,20 @@ jobs:
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
|
||||
# - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消此区域注释
|
||||
# with:
|
||||
# version: 9
|
||||
# - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
|
||||
- name: Setup Node
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm # 或 pnpm / yarn
|
||||
cache: npm
|
||||
cache-dependency-path: docs/package-lock.json
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v4
|
||||
- name: Install dependencies
|
||||
run: npm ci # 或 pnpm install / yarn install / bun install
|
||||
run: npm ci
|
||||
working-directory: docs
|
||||
- name: Build with VitePress
|
||||
run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
|
||||
run: npm run build
|
||||
working-directory: docs
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
|
||||
@ -46,4 +46,4 @@ docker compose exec api uv run python test/your_script.py # 放在 test 文件
|
||||
**其他**：
|
||||
|
||||
- 如果需要新建说明文档（仅开发者可见，非必要不创建），则保存在 `docs/vibe` 文件夹下面
|
||||
- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中。文档应该更新最新版（`docs/latest`）
|
||||
- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中
|
||||
|
||||
@ -48,4 +48,4 @@ docker compose exec api uv run python test/your_script.py # 放在 test 文件
|
||||
|
||||
- 使用 YUXI_SUPER_ADMIN_NAME / YUXI_SUPER_ADMIN_PASSWORD 调试接口
|
||||
- 如果需要新建说明文档（仅开发者可见，非必要不创建），则保存在 `docs/vibe` 文件夹下面
|
||||
- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中。文档应该更新最新版（`docs/latest`）
|
||||
- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中
|
||||
|
||||
2
LICENSE
2
LICENSE
@ -1,6 +1,6 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025 The Project Contributors
|
||||
Copyright (c) 2025 Yuxi Project Contributors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
||||
5
Makefile
5
Makefile
@ -1,5 +1,5 @@
|
||||
|
||||
.PHONY: up down logs lint format format_diff router-tests
|
||||
.PHONY: up down logs lint format
|
||||
|
||||
PYTEST_ARGS ?=
|
||||
|
||||
@ -33,6 +33,3 @@ format:
|
||||
cd backend && uv run ruff check package --fix
|
||||
cd backend && uv run ruff check --select I package --fix
|
||||
docker compose exec -T web pnpm run format
|
||||
|
||||
router-tests:
|
||||
docker compose exec -T api uv run --group test pytest test/api $(PYTEST_ARGS)
|
||||
|
||||
@ -8,7 +8,6 @@ export default defineConfig({
|
||||
title: "Yuxi",
|
||||
description: "语析",
|
||||
base: '/Yuxi-Know/',
|
||||
srcDir: './',
|
||||
ignoreDeadLinks: [
|
||||
/localhost/
|
||||
],
|
||||
@ -21,95 +20,63 @@ export default defineConfig({
|
||||
// https://vitepress.dev/reference/default-theme-config
|
||||
logo: "/favicon.svg",
|
||||
nav: [
|
||||
{
|
||||
text: 'Version',
|
||||
items: [
|
||||
{ text: 'Latest (开发版)', link: '/latest/intro/quick-start' },
|
||||
{ text: 'v0.4.0 (稳定版)', link: '/v0.4.0/intro/quick-start' }
|
||||
]
|
||||
}
|
||||
{ text: '快速开始', link: '/intro/quick-start' },
|
||||
{ text: '智能体开发', link: '/agents/agents-config' }
|
||||
],
|
||||
|
||||
sidebar: {
|
||||
'/latest/': [
|
||||
sidebar: [
|
||||
{
|
||||
text: '简介',
|
||||
items: [
|
||||
{ text: '什么是 Yuxi？', link: '/latest/intro/project-overview' },
|
||||
{ text: '快速开始', link: '/latest/intro/quick-start' },
|
||||
{ text: '模型配置', link: '/latest/intro/model-config' },
|
||||
{ text: '知识库与知识图谱', link: '/latest/intro/knowledge-base' },
|
||||
{ text: '知识库评估', link: '/latest/intro/evaluation' }
|
||||
{ text: '什么是 Yuxi？', link: '/intro/project-overview' },
|
||||
{ text: '快速开始', link: '/intro/quick-start' },
|
||||
{ text: '模型配置', link: '/intro/model-config' },
|
||||
{ text: '知识库与知识图谱', link: '/intro/knowledge-base' },
|
||||
{ text: '知识库评估', link: '/intro/evaluation' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '智能体开发',
|
||||
items: [
|
||||
{ text: '智能体配置', link: '/latest/agents/agents-config' },
|
||||
{ text: '上下文配置', link: '/latest/agents/context-config' },
|
||||
{ text: '工具系统', link: '/latest/agents/tools-system' },
|
||||
{ text: '中间件', link: '/latest/agents/middleware' },
|
||||
{ text: 'MCP 集成', link: '/latest/agents/mcp-integration' },
|
||||
{ text: 'Skills 管理', link: '/latest/agents/skills-management' },
|
||||
{ text: 'SubAgents 管理', link: '/latest/agents/subagents-management' }
|
||||
{ text: '智能体配置', link: '/agents/agents-config' },
|
||||
{ text: '上下文配置', link: '/agents/context-config' },
|
||||
{ text: '工具系统', link: '/agents/tools-system' },
|
||||
{ text: '中间件', link: '/agents/middleware' },
|
||||
{ text: 'MCP 集成', link: '/agents/mcp-integration' },
|
||||
{ text: 'Skills 管理', link: '/agents/skills-management' },
|
||||
{ text: 'SubAgents 管理', link: '/agents/subagents-management' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '高级配置',
|
||||
items: [
|
||||
{ text: '配置系统详解', link: '/latest/advanced/configuration' },
|
||||
{ text: '文档解析', link: '/latest/advanced/document-processing' },
|
||||
{ text: '品牌自定义', link: '/latest/advanced/branding' },
|
||||
{ text: '其他配置', link: '/latest/advanced/misc' },
|
||||
{ text: '生产部署', link: '/latest/advanced/deployment' }
|
||||
{ text: '配置系统详解', link: '/advanced/configuration' },
|
||||
{ text: '文档解析', link: '/advanced/document-processing' },
|
||||
{ text: '品牌自定义', link: '/advanced/branding' },
|
||||
{ text: '其他配置', link: '/advanced/misc' },
|
||||
{ text: '生产部署', link: '/advanced/deployment' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '更新日志',
|
||||
items: [
|
||||
{ text: '路线图', link: '/latest/changelog/roadmap' },
|
||||
{ text: '参与贡献', link: '/latest/changelog/contributing' },
|
||||
{ text: '常见问题', link: '/latest/changelog/faq' },
|
||||
{ text: '迁移至 v0.5', link: '/latest/changelog/migrate_to_v0-5' }
|
||||
{ text: '路线图', link: '/changelog/roadmap' },
|
||||
{ text: '参与贡献', link: '/changelog/contributing' },
|
||||
{ text: '常见问题', link: '/changelog/faq' },
|
||||
{ text: '迁移至 v0.5', link: '/changelog/migrate_to_v0-5' }
|
||||
]
|
||||
}
|
||||
],
|
||||
'/v0.4.0/': [
|
||||
{
|
||||
text: '简介',
|
||||
items: [
|
||||
{ text: '什么是 Yuxi？', 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.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: [
|
||||
{ icon: 'github', link: 'https://github.com/xerrors/Yuxi-Know' }
|
||||
],
|
||||
|
||||
|
||||
footer: {
|
||||
message: '本项目基于 MIT License 开源，欢迎使用和贡献。',
|
||||
copyright: 'Copyright © 2025-present Yuxi'
|
||||
},
|
||||
|
||||
|
||||
editLink: {
|
||||
pattern: 'https://github.com/xerrors/Yuxi-Know/edit/main/docs/:path',
|
||||
text: '在 GitHub 上编辑此页'
|
||||
@ -127,7 +94,6 @@ export default defineConfig({
|
||||
provider: 'local'
|
||||
},
|
||||
|
||||
|
||||
docFooter: {
|
||||
prev: '上一页',
|
||||
next: '下一页'
|
||||
|
||||
@ -10,10 +10,10 @@
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
bash docker/pull_image.sh
|
||||
bash scripts/pull_image.sh
|
||||
|
||||
# Windows PowerShell
|
||||
powershell -ExecutionPolicy Bypass -File docker/pull_image.ps1
|
||||
powershell -ExecutionPolicy Bypass -File scripts/pull_image.ps1
|
||||
```
|
||||
|
||||
**构建失败问题**：
|
||||
@ -57,8 +57,8 @@
|
||||
## v0.4
|
||||
|
||||
### 新增
|
||||
- 新增对于上传附件的智能体中间件，详见[文档](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)
|
||||
- 新增对于上传附件的智能体中间件，详见[文档](https://xerrors.github.io/Yuxi-Know/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/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)
|
||||
- 新建 DeepAgents 智能体（深度分析智能体），支持 todo，files 等渲染，支持文件的下载。
|
||||
- 新增基于知识库文件生成思维导图功能（[#335](https://github.com/xerrors/Yuxi-Know/pull/335#issuecomment-3530976425)）
|
||||
- 新增基于知识库文件生成示例问题功能（[#335](https://github.com/xerrors/Yuxi-Know/pull/335#issuecomment-3530976425)）
|
||||
@ -66,10 +66,10 @@
|
||||
- 新增自定义模型支持、新增 dashscope rerank/embeddings 模型的支持
|
||||
- 新增文档解析的图片支持，已支持 MinerU Officical、Docs、Markdown Zip格式
|
||||
- 新增暗色模式支持并调整整体 UI（[#343](https://github.com/xerrors/Yuxi-Know/pull/343)）
|
||||
- 新增知识库评估功能，支持导入评估基准或者自动构建评估基准（目前仅支持Milvus类型知识库）详见[文档](https://xerrors.github.io/Yuxi-Know/latest/intro/evaluation.html)
|
||||
- 新增知识库评估功能，支持导入评估基准或者自动构建评估基准（目前仅支持Milvus类型知识库）详见[文档](https://xerrors.github.io/Yuxi-Know/intro/evaluation.html)
|
||||
- 新增同名文件处理逻辑：遇到同名文件则在上传区域提示，是否删除旧文件
|
||||
- 新增生产环境部署脚本，固定 python 依赖版本，提升部署稳定性
|
||||
- 优化图谱可视化方式，统一图谱数据结构，统一使用基于 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)
|
||||
- 优化图谱可视化方式，统一图谱数据结构，统一使用基于 G6 的可视化方式，同时支持上传带属性的图谱文件，详见[文档](https://xerrors.github.io/Yuxi-Know/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，支持异步操作
|
||||
- 优化 知识库详情页面，更加简洁清晰，增强文件下载功能
|
||||
|
||||
@ -11,11 +11,8 @@ hero:
|
||||
alt: VitePress
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Latest 文档
|
||||
link: /latest/intro/quick-start
|
||||
- theme: alt
|
||||
text: v0.4.0 文档
|
||||
link: /v0.4.0/intro/quick-start
|
||||
text: 快速开始
|
||||
link: /intro/quick-start
|
||||
|
||||
features:
|
||||
- title: 🤖 智能体与模型
|
||||
|
||||
@ -119,13 +119,13 @@ docker logs web-dev -f
|
||||
|
||||
```bash
|
||||
# 手动拉取基础镜像
|
||||
bash docker/pull_image.sh python:3.12-slim
|
||||
bash scripts/pull_image.sh python:3.12-slim
|
||||
```
|
||||
|
||||
**离线环境部署方案**：
|
||||
|
||||
```bash
|
||||
# 在有网络的环境导出镜像
|
||||
# 在有网络的环境导出镜像，注意检查镜像列表，不一定是最新的。
|
||||
bash docker/save_docker_images.sh
|
||||
|
||||
# 传输到目标机器
|
||||
11
docs/package.json
Normal file
11
docs/package.json
Normal file
@ -0,0 +1,11 @@
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "vitepress dev",
|
||||
"build": "vitepress build",
|
||||
"preview": "vitepress preview"
|
||||
},
|
||||
"dependencies": {
|
||||
"markdown-it-task-checkbox": "^1.0.6",
|
||||
"vitepress": "^1.6.4"
|
||||
}
|
||||
}
|
||||
@ -1,272 +0,0 @@
|
||||
# 智能体
|
||||
|
||||
## 智能体开发
|
||||
|
||||
系统基于 [LangGraph](https://github.com/langchain-ai/langgraph) 并通过统一的 `AgentManager` 管理所有智能体。`backend/package/yuxi/agents/__init__.py` 会在启动时遍历 `backend/package/yuxi/agents` 目录，对每个包含 `__init__.py` 的子包执行自动发现：所有继承 `BaseAgent` 的类都会被注册并立即初始化，因此只要代码落位正确，就不需要再手动登记或修改管理器。
|
||||
|
||||
仓库预置了若干可直接运行的智能体：`chatbot` 聚焦对话与动态工具调度，`reporter` 演示报告类链路。这些目录展示了上下文类、Graph 构造方式、子智能体引用以及中间件组合的范例，新增功能时可以直接复用。
|
||||
|
||||
### 智能体元数据配置
|
||||
|
||||
每个智能体可以通过在智能体目录下创建 `metadata.toml` 文件来配置元数据信息。这个文件使用 TOML 格式，包含以下字段：
|
||||
|
||||
- `name`: 智能体显示名称
|
||||
- `description`: 智能体功能描述
|
||||
- `examples`: 示例问题列表（数组格式）
|
||||
|
||||
例如，`backend/package/yuxi/agents/chatbot/metadata.toml`：
|
||||
|
||||
<<< @/../backend/package/yuxi/agents/chatbot/metadata.toml
|
||||
|
||||
**注意**：`metadata.toml` 文件是可选的，如果没有提供，系统将使用智能体类的基本属性。
|
||||
|
||||
### 创建新的智能体
|
||||
|
||||
在 `backend/package/yuxi/agents` 下新建一个包，保持与现有目录一致的结构：放置 Graph 构造逻辑（通常命名为 `graph.py`），并在包内的 `__init__.py` 中暴露主类。
|
||||
|
||||
智能体类必须继承 `yuxi.agents.common.BaseAgent`，同时实现异步的 `get_graph` 方法来返回编译后的 LangGraph 实例，并配置好 `checkpointer`，否则无法从历史对话中恢复。
|
||||
|
||||
需要额外上下文字段时，可继承 `BaseContext` 构建自己的配置表单，再把类绑定到 `context_schema`，平台会在 `saves/agents/<module>` 下生成默认配置。
|
||||
|
||||
案例 基于MySQL工具，以及自定义 MCP Server 的数据库报表助手。
|
||||
|
||||
<<< @/../backend/package/yuxi/agents/reporter/graph.py
|
||||
|
||||
|
||||
|
||||
智能体实例的生命周期交给管理器处理，会在自动发现时完成初始化并缓存单例，以便快速响应请求。在容器内热重载时，只要保存文件即可触发重新导入；需要强制刷新可调用 `agent_manager.get_agent(<id>, reload=True)`。
|
||||
|
||||
更多动态工具选择与 MCP 注册的例子，见 `backend/package/yuxi/agents/chatbot/graph.py` 中的中间件组合。
|
||||
|
||||
### 拓展现有智能体
|
||||
|
||||
智能体保持为 LangGraph 的标准节点组合，因此可以在原有 `graph.py` 中添加节点、条件与消息转换器。复用现成上下文时，只需扩展当前 `context_schema` 的字段；若功能差异较大，可以创建新的上下文类并替换 `context_schema`。
|
||||
|
||||
对工具、模型或提示语的调整建议封装到中间件或独立函数里，既方便多智能体共用，又能保持 `BaseAgent` 的基础接口稳定。变更提交后无需手动刷新注册表，只要确保包结构未改变，智能体会在热重载中自动更新。
|
||||
|
||||
### 子智能体与中间件
|
||||
|
||||
子智能体集中放在 `backend/package/yuxi/agents/common/subagents` 目录，典型例子是 `calc_agent`，它通过 LangChain 的 `create_agent` 构建计算器能力并以工具暴露给主图。新增子智能体时沿用这一结构：在目录内编写封装函数与 `@tool` 装饰器，导出后即可被任意智能体调用。
|
||||
|
||||
中间件位于 `backend/package/yuxi/agents/common/middlewares`，包含上下文感知提示词、模型选择、动态工具加载以及附件注入等实现。如果需要编写新的中间件，请遵循 LangChain 官方文档中对 `AgentMiddleware`、`ModelRequest`、`ModelResponse` 等接口的定义，完成后在该目录的 `__init__.py` 暴露入口，主智能体即可在 `middleware` 列表中引用。
|
||||
|
||||
#### 文件上传中间件
|
||||
|
||||
文件上传功能通过 `inject_attachment_context` 中间件实现（位于 `backend/package/yuxi/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 yuxi.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 的接入方式保持不变，只需在 `backend/package/yuxi/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", "backend/package/yuxi/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 yuxi.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，智能体可以自动陈述数据库用途并选择更准确的检索策略。详见代码部分 `backend/package/yuxi/agents/common/toolkits/mysql/`
|
||||
|
||||
### 多模态图片支持
|
||||
|
||||
系统支持接收图片作为输入，与文本结合形成多模态查询。图片支持的核心特性如下：
|
||||
|
||||
#### 1. 图片上传与处理
|
||||
- 通过 `/chat/image/upload` 接口上传图片
|
||||
- 自动处理图片格式转换和压缩
|
||||
- 返回 base64 编码的图片数据
|
||||
- 图片大小限制为 10MB
|
||||
- 支持的图片格式：JPEG、PNG、WebP、GIF、BMP
|
||||
- 自动压缩超过 5MB 的图片
|
||||
|
||||
当发送包含图片的请求时，消息格式为：
|
||||
```json
|
||||
{
|
||||
"query": "这张图片里有什么？",
|
||||
"image_content": "<base64编码的图片数据>",
|
||||
"config": {},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
智能体会自动识别多模态消息并将其传递给支持图片的模型。如果模型不支持图片，会自动忽略图片内容，只处理文本部分。系统会将图片转换为符合模型要求的格式（通常是 base64 编码的 JPEG 或 PNG），确保与主流多模态模型兼容。
|
||||
|
||||
目前仅支持上传单个图片，图片以 base64 编码形式存储在数据库。系统会自动处理图片的格式转换和压缩，并生成缩略图以优化性能。
|
||||
|
||||
### 图片上传响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"image_content": "<base64编码的原始图片数据>",
|
||||
"thumbnail_content": "<base64编码的缩略图数据>",
|
||||
"width": 1024,
|
||||
"height": 768,
|
||||
"format": "JPEG",
|
||||
"mime_type": "image/jpeg"
|
||||
}
|
||||
```
|
||||
|
||||
系统会将图片信息与用户查询一同传递给支持多模态的模型，并自动适配模型要求的格式。
|
||||
@ -1,60 +0,0 @@
|
||||
# 品牌自定义
|
||||
|
||||
系统支持完整的品牌信息自定义，包括 Logo、组织名称、版权信息等。
|
||||
|
||||
## 配置方法
|
||||
|
||||
### 1. 复制模板文件
|
||||
|
||||
```bash
|
||||
cp backend/package/yuxi/config/static/info.template.yaml backend/package/yuxi/config/static/info.local.yaml
|
||||
```
|
||||
|
||||
### 2. 编辑品牌信息
|
||||
|
||||
在 `backend/package/yuxi/config/static/info.local.yaml` 中配置：
|
||||
|
||||
<<< @/../backend/package/yuxi/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=backend/package/yuxi/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 编程可以设计出更好看的首页的）
|
||||
@ -1,185 +0,0 @@
|
||||
# 配置系统详解
|
||||
|
||||
## 概述
|
||||
|
||||
Yuxi-Know 从 v0.3.x 版本开始采用了全新的配置系统，基于 Pydantic BaseModel 和 TOML 格式，提供了类型安全、智能提示和选择性持久化等现代化特性。
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 配置层次结构
|
||||
|
||||
```
|
||||
配置系统架构
|
||||
├── 默认配置 (代码定义)
|
||||
│ ├── backend/package/yuxi/config/static/models.py (模型配置)
|
||||
│ └── backend/package/yuxi/config/app.py (应用配置)
|
||||
├── 用户配置 (TOML 文件)
|
||||
│ └── saves/config/base.toml (仅保存用户修改)
|
||||
└── 环境变量 (运行时覆盖)
|
||||
└── .env 文件
|
||||
```
|
||||
|
||||
### 核心组件
|
||||
|
||||
#### 1. Config 类 (`backend/package/yuxi/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. 模型配置类 (`backend/package/yuxi/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
|
||||
```
|
||||
|
||||
### 默认模型配置 (`backend/package/yuxi/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 yuxi.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 yuxi.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
|
||||
}
|
||||
@ -1,69 +0,0 @@
|
||||
# 生产部署指南
|
||||
|
||||
本指南介绍了如何在生产环境中部署 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
|
||||
```
|
||||
@ -1,120 +0,0 @@
|
||||
# 文档处理与 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 环境和基础识别需求
|
||||
@ -1,53 +0,0 @@
|
||||
# 其他配置
|
||||
|
||||
## 内容安全
|
||||
|
||||
系统内置内容审查机制（默认是关闭状态），保障服务内容的合规性。目前配置了关键词过滤以及 LLM 对内容进行审查。管理员可在 `设置` → `基本设置` 页面中进行配置并选择安全模型。
|
||||
|
||||
检测流程为，接收到用户输入之后，就对用户的输入进行检测是否合规，同时在流式传输的过程中进行实时检测（仅关键词）。当流式输出结束之后，则开始检测整个内容。
|
||||
**注意**，使用 LLM 检测虽然可以大大缓解提示词注入带来的问题，但也会在用户交互上带来延迟影响，需要考虑是否启用。
|
||||
|
||||
对于关键词检测，敏感词词库位于 `backend/package/yuxi/config/static/bad_keywords.txt` 文件，每行一个关键词，实时生效，无需重启服务。
|
||||
|
||||
对于 LLM 检测，Prompt 可以看到 `backend/package/yuxi/plugins/guard.py`：
|
||||
|
||||
<<< @/../backend/package/yuxi/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`
|
||||
:::
|
||||
@ -1,57 +0,0 @@
|
||||
# 知识库评估使用与开发指南
|
||||
|
||||
知识库评估功能用于测试 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 理解和表达能力 |
|
||||
@ -1,117 +0,0 @@
|
||||
# 知识库与知识图谱
|
||||
|
||||
项目中的知识库与知识图谱，即是知识管理组织的方式，同时会被封装为工具供 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` 类型，否则会影响图的检索与构建功能。
|
||||
:::
|
||||
@ -1,227 +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` 文件中添加对应的环境变量：
|
||||
|
||||
|
||||
|
||||
::: 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 格式的用户配置文件。
|
||||
|
||||
- **默认配置**: `backend/package/yuxi/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. 配置模型信息
|
||||
|
||||
在 `backend/package/yuxi/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 yuxi.config import config
|
||||
from yuxi.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
|
||||
```
|
||||
@ -1,24 +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、图片等多种格式的智能解析
|
||||
- **权限管理**: 三级权限体系（超级管理员、管理员、普通用户）
|
||||
- **内容安全**: 内置内容审查机制，保障服务合规性
|
||||
@ -1,178 +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.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
|
||||
```
|
||||
|
||||
## 对话
|
||||
|
||||
项目第一次启动后，会要求填写超级管理员账号和密码，请确保填写正确。
|
||||
|
||||
然后在智能体页面可以进行对话，在右侧可以配置提示词、模型、工具等参数。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 故障排除
|
||||
|
||||
#### 查看服务状态
|
||||
|
||||
```bash
|
||||
# 查看所有容器状态
|
||||
docker ps
|
||||
|
||||
# 查看后端服务日志
|
||||
docker logs api-dev -f
|
||||
|
||||
# 查看前端服务日志
|
||||
docker logs web-dev -f
|
||||
```
|
||||
|
||||
#### 常见问题
|
||||
|
||||
<details>
|
||||
<summary><strong>Docker 镜像拉取失败</strong></summary>
|
||||
|
||||
如果拉取镜像失败，可以尝试手动拉取：
|
||||
|
||||
```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 <user>@<dev_host>:<path_to_save>
|
||||
|
||||
# 在目标设备加载镜像
|
||||
docker load -i docker_images_xxx.tar
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>构建失败</strong></summary>
|
||||
|
||||
如果构建失败，通常是网络问题，可以配置代理：
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
如果已配置代理但构建失败，尝试移除代理后重试。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Milvus 启动失败</strong></summary>
|
||||
|
||||
```bash
|
||||
# 重启 Milvus 服务
|
||||
docker compose up milvus -d
|
||||
docker restart api-dev
|
||||
```
|
||||
|
||||
</details>
|
||||
2344
package-lock.json
generated
2344
package-lock.json
generated
File diff suppressed because it is too large
Load Diff
12
package.json
12
package.json
@ -1,12 +0,0 @@
|
||||
{
|
||||
"scripts": {
|
||||
"docs:dev": "vitepress dev docs",
|
||||
"docs:build": "vitepress build docs",
|
||||
"docs:preview": "vitepress preview docs",
|
||||
"docs:host": "vitepress dev docs --host"
|
||||
},
|
||||
"dependencies": {
|
||||
"markdown-it-task-checkbox": "^1.0.6",
|
||||
"vitepress": "^1.6.4"
|
||||
}
|
||||
}
|
||||
@ -68,13 +68,14 @@ $images = @(
|
||||
"nginx:alpine",
|
||||
"quay.io/coreos/etcd:v3.5.5",
|
||||
"postgres:16"
|
||||
"redis:7-alpine"
|
||||
)
|
||||
|
||||
# Pull each image
|
||||
foreach ($image in $images) {
|
||||
Write-Host "🔄 Pulling ${image}..." -ForegroundColor Yellow
|
||||
try {
|
||||
& docker/pull_image.ps1 $image
|
||||
& scripts/pull_image.ps1 $image
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
Write-Host "✅ Successfully pulled ${image}" -ForegroundColor Green
|
||||
} else {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user