docs: 更新文档，添加智能体开发、品牌自定义、文档解析等新内容，并优化快速开始指南
This commit is contained in:
Wenjie Zhang
parent
2671b60dff
commit
b866ddfec2
@ -23,6 +23,7 @@ services:
|
||||
- "host.docker.internal:host-gateway"
|
||||
env_file:
|
||||
- src/.env
|
||||
# region api_envs
|
||||
environment:
|
||||
- HOST_IP=${HOST_IP:-}
|
||||
- NEO4J_URI=${NEO4J_URI:-bolt://graph:7687}
|
||||
@ -37,6 +38,7 @@ services:
|
||||
- RUNNING_IN_DOCKER=true
|
||||
- NO_PROXY=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex
|
||||
- no_proxy=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex
|
||||
# endregion api_envs
|
||||
command: uv run --no-dev uvicorn server.main:app --host 0.0.0.0 --port 5050 --reload
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
@ -105,6 +107,7 @@ services:
|
||||
# restart: unless-stopped
|
||||
# command: ["bash", "/init-postgres.sh"]
|
||||
|
||||
# region neo4j
|
||||
graph:
|
||||
image: neo4j:5.26
|
||||
container_name: graph
|
||||
@ -128,6 +131,7 @@ services:
|
||||
networks:
|
||||
- app-network
|
||||
restart: unless-stopped
|
||||
# endregion neo4j
|
||||
|
||||
etcd:
|
||||
container_name: milvus-etcd-dev
|
||||
|
||||
@ -24,13 +24,27 @@ export default defineConfig({
|
||||
{
|
||||
text: '简介',
|
||||
items: [
|
||||
{ text: '快速开始', link: '/intro/quick-start' }
|
||||
{ text: '什么是 Yuxi-Know？', link: '/intro/project-overview' },
|
||||
{ text: '快速开始', link: '/intro/quick-start' },
|
||||
{ text: '模型配置', link: '/intro/model-config' },
|
||||
{ text: '知识库与知识图谱', link: '/intro/knowledge-base' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '高级配置',
|
||||
items: [
|
||||
{ text: '文档解析', link: '/advanced/document-processing' },
|
||||
{ text: '智能体', link: '/advanced/agents' },
|
||||
{ text: '品牌自定义', link: '/advanced/branding' },
|
||||
{ text: '其他配置', link: '/advanced/misc' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '更新日志',
|
||||
items: [
|
||||
{ text: '更新日志', link: '/changelog/update' }
|
||||
{ text: '路线图', link: '/changelog/roadmap' },
|
||||
{ text: '参与贡献', link: '/changelog/contributing' },
|
||||
{ text: '常见问题', link: '/changelog/faq' }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
119
docs/advanced/agents.md
Normal file
119
docs/advanced/agents.md
Normal file
@ -0,0 +1,119 @@
|
||||
# 智能体
|
||||
|
||||
## 智能体开发
|
||||
|
||||
系统基于 [LangGraph](https://github.com/langchain-ai/langgraph) 框架，支持自定义智能体应用开发。
|
||||
|
||||
系统默认集成示例智能体：
|
||||
|
||||
| 智能体 | 功能 | 位置 |
|
||||
|--------|------|------|
|
||||
| **基础智能体** | 对话功能 | `src/agents/chatbot/` |
|
||||
| **ReAct 智能体** | 推理与行动循环 | `src/agents/react/` |
|
||||
|
||||
### 开发自定义智能体
|
||||
|
||||
如果需要开发自己的智能体的话，可以基于智能体基类以及相关脚手架实现。整体上是和 LangGraph 的架构是适配的，只是在部分功能上需要和平台更加适配才好。
|
||||
|
||||
#### 1. 创建智能体类
|
||||
|
||||
继承 `BaseAgent` 并实现 `get_graph` 方法：
|
||||
|
||||
```python
|
||||
from .base import BaseAgent
|
||||
|
||||
class CustomAgent(BaseAgent):
|
||||
def get_graph(self):
|
||||
# 返回 LangGraph 实例
|
||||
return graph_instance
|
||||
|
||||
@property
|
||||
def context_schema(self):
|
||||
# 定义配置参数
|
||||
return schema
|
||||
```
|
||||
|
||||
#### 2. 注册智能体
|
||||
|
||||
在 `src/agents/__init__.py` 中注册：
|
||||
|
||||
```python
|
||||
from .custom_agent import CustomAgent
|
||||
|
||||
agent_manager = AgentManager()
|
||||
agent_manager.register_agent(CustomAgent)
|
||||
agent_manager.init_all_agents()
|
||||
```
|
||||
|
||||
#### 3. 参考示例
|
||||
|
||||
查看 `src/agents/react/graph.py` 中的 `ReActAgent` 实现示例。
|
||||
|
||||
## 内置工具与 MCP 集成
|
||||
|
||||
|
||||
::: warning
|
||||
文档待完善
|
||||
:::
|
||||
|
||||
|
||||
### 1. MySQL 数据库集成
|
||||
|
||||
系统支持智能体查询 MySQL 数据库，为数据分析提供强大支持。
|
||||
|
||||
### 配置数据库连接
|
||||
|
||||
在环境变量中配置数据库信息：
|
||||
|
||||
```env
|
||||
# MySQL 数据库配置
|
||||
MYSQL_HOST=192.168.1.100
|
||||
MYSQL_USER=username
|
||||
MYSQL_PASSWORD=your_secure_password
|
||||
MYSQL_DATABASE=database_name
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_CHARSET=utf8mb4
|
||||
```
|
||||
|
||||
在智能体配置中启用以下 MySQL 工具：
|
||||
|
||||
| 工具名称 | 功能描述 |
|
||||
|----------|----------|
|
||||
| `mysql_list_tables` | 获取数据库中的所有表名 |
|
||||
| `mysql_describe_table` | 获取指定表的详细结构信息 |
|
||||
| `mysql_query` | 执行只读的 SQL 查询语句 |
|
||||
|
||||
### 安全特性
|
||||
|
||||
- ✅ **只读操作**: 仅允许 SELECT、SHOW、DESCRIBE、EXPLAIN 操作
|
||||
- ✅ **SQL 注入防护**: 严格的表名参数验证
|
||||
- ✅ **超时控制**: 默认 10 秒，最大 60 秒
|
||||
- ✅ **结果限制**: 默认 10000 字符，100 行，最大 1000 行
|
||||
|
||||
### 可视化图表-MCP-Server
|
||||
|
||||
系统支持基于 MCP（Model Context Protocol）的图表可视化功能。
|
||||
|
||||
- 基于 @antvis 团队开发的 [可视化图表-MCP-Server](https://www.modelscope.cn/mcp/servers/@antvis/mcp-server-chart)
|
||||
- 支持多种图表类型和数据可视化
|
||||
- 通过魔搭社区配置 Host 资源
|
||||
|
||||
在 `src/agents/common/mcp.py` 的 `MCP_SERVERS` 中添加配置：
|
||||
|
||||
```python
|
||||
# MCP Server configurations
|
||||
MCP_SERVERS = {
|
||||
"sequentialthinking": {
|
||||
"url": "https://remote.mcpservers.org/sequentialthinking/mcp",
|
||||
"transport": "streamable_http",
|
||||
},
|
||||
"mcp-server-chart": {
|
||||
"url": "https://mcp.api-inference.modelscope.net/9993ae42524c4c/mcp",
|
||||
"transport": "streamable_http",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: warning 配置注意
|
||||
记得将 `type` 字段修改为 `transport`。
|
||||
:::
|
||||
49
docs/advanced/branding.md
Normal file
49
docs/advanced/branding.md
Normal file
@ -0,0 +1,49 @@
|
||||
# 品牌自定义
|
||||
|
||||
系统支持完整的品牌信息自定义，包括 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; /* 边框色 */
|
||||
}
|
||||
```
|
||||
110
docs/advanced/document-processing.md
Normal file
110
docs/advanced/document-processing.md
Normal file
@ -0,0 +1,110 @@
|
||||
# 文档解析
|
||||
|
||||
## OCR 服务
|
||||
|
||||
系统提供多种 OCR 服务选项，满足不同精度和性能需求。
|
||||
|
||||
### 基础 OCR 服务
|
||||
|
||||
使用 RapidOCR ONNX 版本，无需 GPU 支持：
|
||||
|
||||
#### 1. 下载模型
|
||||
|
||||
```bash
|
||||
huggingface-cli download SWHL/RapidOCR --local-dir ${MODEL_DIR:-./models}/SWHL/RapidOCR
|
||||
```
|
||||
|
||||
#### 2. 模型要求
|
||||
|
||||
确保以下文件存在：
|
||||
- `PP-OCRv4/ch_PP-OCRv4_det_infer.onnx`
|
||||
- `PP-OCRv4/ch_PP-OCRv4_rec_infer.onnx`
|
||||
|
||||
::: warning 权限问题
|
||||
如果提示 `[Errno 13] Permission denied`，需要使用 sudo 修改权限后执行。
|
||||
:::
|
||||
|
||||
### 高级 OCR 服务
|
||||
|
||||
为提升 PDF 解析准确性，可选择以下 GPU 加速服务：
|
||||
|
||||
#### 1. MinerU 服务（推荐）
|
||||
|
||||
```bash
|
||||
# 需要 CUDA 12.6+ 环境
|
||||
docker compose up mineru --build
|
||||
```
|
||||
|
||||
#### 2. PP-Structure-V3 服务
|
||||
|
||||
```bash
|
||||
# 需要 CUDA 11.8+ 环境
|
||||
docker compose up paddlex --build
|
||||
```
|
||||
|
||||
**配置文件**: `docker/PP-StructureV3.yaml`
|
||||
|
||||
### OCR 服务选择建议
|
||||
|
||||
- **基础使用**: RapidOCR（无需 GPU）
|
||||
- **高精度需求**: MinerU（推荐）
|
||||
- **结构化文档**: PP-Structure-V3
|
||||
- **生产环境**: 根据硬件条件选择
|
||||
|
||||
## 批量处理脚本
|
||||
|
||||
系统提供便捷的批量处理脚本，支持文件上传和解析操作。
|
||||
|
||||
### 文件上传脚本
|
||||
|
||||
使用 `scripts/batch_upload.py upload` 批量上传文件到知识库：
|
||||
|
||||
```bash
|
||||
# 批量上传文档
|
||||
uv run scripts/batch_upload.py upload \
|
||||
--db-id your_kb_id \
|
||||
--directory path/to/your/data \
|
||||
--pattern "*.docx" \
|
||||
--base-url http://127.0.0.1:5050/api \
|
||||
--username your_username \
|
||||
--password your_password \
|
||||
--concurrency 4 \
|
||||
--recursive \
|
||||
--record-file scripts/tmp/batch_processed_files.txt
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
- `--db-id`: 目标知识库 ID
|
||||
- `--directory`: 文件目录路径
|
||||
- `--pattern`: 文件匹配模式
|
||||
- `--concurrency`: 并发处理数量
|
||||
- `--recursive`: 递归处理子目录
|
||||
- `--record-file`: 处理记录文件路径
|
||||
|
||||
### 文件解析脚本
|
||||
|
||||
使用 `scripts/batch_upload.py trans` 将文件解析为 Markdown：
|
||||
|
||||
```bash
|
||||
# 批量解析文档
|
||||
uv run scripts/batch_upload.py trans \
|
||||
--db-id your_kb_id \
|
||||
--directory path/to/your/data \
|
||||
--output-dir path/to/output_markdown \
|
||||
--pattern "*.docx" \
|
||||
--base-url http://127.0.0.1:5050/api \
|
||||
--username your_username \
|
||||
--password your_password \
|
||||
--concurrency 4 \
|
||||
--recursive
|
||||
```
|
||||
|
||||
**输出结果**: 解析后的 Markdown 文件将保存到指定输出目录。
|
||||
|
||||
### 脚本功能
|
||||
|
||||
- **进度跟踪**: 实时显示处理进度
|
||||
- **错误处理**: 自动跳过无法处理的文件
|
||||
- **断点续传**: 支持中断后继续处理
|
||||
- **日志记录**: 详细记录处理过程
|
||||
- **结果统计**: 处理完成后显示统计信息
|
||||
28
docs/advanced/misc.md
Normal file
28
docs/advanced/misc.md
Normal file
@ -0,0 +1,28 @@
|
||||
# 其他配置
|
||||
|
||||
## 内容安全
|
||||
|
||||
系统内置内容审查机制，保障服务内容的合规性。目前配置了关键词过滤以及 LLM 对内容进行审查。管理员可在 `设置` → `基本设置` 页面中进行配置并选择安全模型。
|
||||
|
||||
敏感词词库位于 `src/config/static/bad_keywords.txt` 文件，每行一个关键词，实时生效，无需重启服务。
|
||||
|
||||
## 服务端口
|
||||
|
||||
系统使用多个端口提供不同服务，以下是完整的端口映射：
|
||||
|
||||
| 端口 | 服务 | 容器名称 | 说明 |
|
||||
|------|------|----------|------|
|
||||
| **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
|
||||
:::
|
||||
75
docs/changelog/contributing.md
Normal file
75
docs/changelog/contributing.md
Normal file
@ -0,0 +1,75 @@
|
||||
# 参与贡献
|
||||
|
||||
感谢所有贡献者的支持！
|
||||
|
||||
<a href="https://github.com/xerrors/Yuxi-Know/contributors">
|
||||
<img src="https://contributors.nn.ci/api?repo=xerrors/Yuxi-Know" alt="贡献者名单">
|
||||
</a>
|
||||
|
||||
## 如何贡献
|
||||
|
||||
### 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: 构建过程或辅助工具的变动
|
||||
```
|
||||
|
||||
### 测试要求
|
||||
|
||||
::: info
|
||||
部分测试脚本待补充
|
||||
:::
|
||||
|
||||
- 确保所有测试通过
|
||||
- 添加新功能的测试用例
|
||||
- 验证现有功能不受影响
|
||||
- 测试不同环境下的兼容性
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目基于 MIT License 开源，贡献的代码将遵循相同的许可证。
|
||||
|
||||
2
docs/changelog/faq.md
Normal file
2
docs/changelog/faq.md
Normal file
@ -0,0 +1,2 @@
|
||||
# 常见问题
|
||||
|
||||
@ -1,8 +1,9 @@
|
||||
# 开发计划
|
||||
# 开发路线图
|
||||
|
||||
📝 0.3 version
|
||||
路线图可能会经常变更，如果有强烈的建议，可以在 [issue](https://github.com/xerrors/Yuxi-Know/issues) 中提。
|
||||
|
||||
## Version 0.3.x
|
||||
|
||||
不再新增任何特性，仅作功能调整以及 bug 修复。
|
||||
|
||||
🐛**BUGs**
|
||||
- [ ] 部分 doc 格式的文件支持有问题
|
||||
@ -19,8 +20,9 @@
|
||||
- [ ] 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示
|
||||
- [ ] 开发与生产环境隔离
|
||||
- [x] 添加统计信息
|
||||
- [ ] 支持 MinerU 的解析方法
|
||||
- [ ] 支持 MinerU 2.5 的解析方法
|
||||
- [ ] Options 中添加网络搜索和绘制图片的选项，分别是用来调用工具
|
||||
- [ ] 移除自定义模型，同时将模型的 env 修改为单环境变量的形式，移除 models.yaml 的私有共有双配置模式，除非配置了环境变量 `OVERRIDE_DEFAULT_MODELS_CONFIG_WITH` 然后指向一个变量。
|
||||
|
||||
📝 **Base**
|
||||
|
||||
@ -28,7 +30,7 @@
|
||||
- [ ] 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。
|
||||
- [ ] 新增 files 模块，用来管理文件上传，下载等
|
||||
|
||||
💯 **More**:
|
||||
## 未来可能会支持
|
||||
|
||||
下面的功能**可能**会放在后续版本实现，暂时未定
|
||||
|
||||
83
docs/intro/knowledge-base.md
Normal file
83
docs/intro/knowledge-base.md
Normal file
@ -0,0 +1,83 @@
|
||||
# 知识库与知识图谱
|
||||
|
||||
项目中的知识库与知识图谱，即是知识管理组织的方式，同时会被封装为工具供 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` 模型进行图谱构建。可通过环境变量自定义图谱构建模型：
|
||||
|
||||
<<< @/../src/.env.template#lightrag{bash}
|
||||
|
||||
|
||||
## 文档管理
|
||||
|
||||
::: danger
|
||||
待补充
|
||||
:::
|
||||
|
||||
## 知识图谱
|
||||
|
||||
::: danger
|
||||
待补充关于知识图谱在项目中的定位
|
||||
:::
|
||||
|
||||
### 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` 中的配置：
|
||||
|
||||
<<< @/../src/.env.template#neo4j{bash}
|
||||
|
||||
同时记得注释掉下面的 neo4j 服务：
|
||||
|
||||
<<< @/../docker-compose.yml#neo4j
|
||||
|
||||
|
||||
::: warning 注意事项
|
||||
确保每个节点都有 `Entity` 标签，每个关系都有 `RELATION` 类型，否则会影响图的检索与构建功能。
|
||||
:::
|
||||
163
docs/intro/model-config.md
Normal file
163
docs/intro/model-config.md
Normal file
@ -0,0 +1,163 @@
|
||||
# 模型配置
|
||||
|
||||
## 对话模型
|
||||
|
||||
系统支持多种大语言模型服务商，通过配置对应的 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 等。
|
||||
|
||||
### 配置方法
|
||||
|
||||
在 `src/.env` 文件中添加对应的环境变量：
|
||||
|
||||
<<< @/../src/.env.template#model_provider{bash 2}
|
||||
|
||||
|
||||
::: tip 免费获取 API Key
|
||||
[硅基流动](https://cloud.siliconflow.cn/i/Eo5yTHGJ) 注册即送 14 元额度，支持多种开源模型。
|
||||
:::
|
||||
|
||||
## 自定义模型供应商
|
||||
|
||||
::: warning
|
||||
原本网页中的自定义模型已在 `0.3.x` 版本移除，请在 `src/config/static/models.yaml` 中按如下方式配置，并重启服务后选择并使用。此外，这里也推荐一下团队的另外一个小工具 [mvllm (Manage and Route vLLM Servers)](https://github.com/xerrors/mvllm)。
|
||||
:::
|
||||
|
||||
系统理论上兼容任何 OpenAI 兼容的模型服务，包括：
|
||||
|
||||
- **vLLM**: 高性能推理服务
|
||||
- **Ollama**: 本地模型管理
|
||||
- **API 中转服务**: 各种代理和聚合服务
|
||||
|
||||
如需添加新的模型供应商，请按以下步骤操作：
|
||||
|
||||
### 1. 编辑模型配置文件
|
||||
|
||||
**方式一：修改公共配置**
|
||||
编辑 `src/config/static/models.yaml` 文件
|
||||
|
||||
**方式二：创建私有配置（推荐）**
|
||||
复制模板并创建私有配置：
|
||||
```bash
|
||||
cp src/config/static/models.yaml src/config/static/models.private.yaml
|
||||
```
|
||||
|
||||
### 2. 添加模型配置
|
||||
|
||||
在配置文件中添加新的模型供应商：
|
||||
|
||||
```yaml
|
||||
custom-provider-name:
|
||||
name: custom-provider-name
|
||||
default: custom-model-name
|
||||
base_url: "https://api.your-provider.com/v1"
|
||||
env:
|
||||
- CUSTOM_API_KEY_ENV_NAME
|
||||
models:
|
||||
- supported-model-name
|
||||
- another-model-name
|
||||
|
||||
|
||||
# 本地 Ollama 服务
|
||||
local-ollama:
|
||||
name: Local Ollama
|
||||
base_url: "http://localhost:11434/v1"
|
||||
default: llama3.2
|
||||
env:
|
||||
- NO_API_KEY
|
||||
models:
|
||||
- llama3.2
|
||||
- qwen2.5
|
||||
|
||||
# 本地 vLLM 服务
|
||||
local-vllm:
|
||||
name: Local 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
|
||||
```
|
||||
|
||||
### 3. 配置环境变量
|
||||
|
||||
在 `src/.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.yaml` 或 `src/config/static/models.private.yaml` 中添加配置：
|
||||
|
||||
```yaml
|
||||
EMBED_MODEL_INFO:
|
||||
vllm/Qwen/Qwen3-Embedding-0.6B:
|
||||
name: Qwen/Qwen3-Embedding-0.6B
|
||||
dimension: 1024
|
||||
base_url: http://localhost:8000/v1/embeddings
|
||||
api_key: no_api_key
|
||||
|
||||
RERANKER_LIST:
|
||||
vllm/BAAI/bge-reranker-v2-m3:
|
||||
name: BAAI/bge-reranker-v2-m3
|
||||
base_url: http://localhost:8000/v1/rerank
|
||||
api_key: no_api_key
|
||||
```
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q: 如何查看当前可用的模型？**
|
||||
|
||||
在 Web 界面的"设置"页面可以查看所有已配置的模型。
|
||||
|
||||
**Q: 模型配置不生效？**
|
||||
|
||||
1. 检查环境变量是否正确设置
|
||||
2. 确认 API 密钥有效
|
||||
3. 重启服务：`docker compose restart api-dev`
|
||||
|
||||
**Q: 如何测试模型连接？**
|
||||
|
||||
在 Web 界面的对话页面选择对应模型进行测试。
|
||||
37
docs/intro/project-overview.md
Normal file
37
docs/intro/project-overview.md
Normal file
@ -0,0 +1,37 @@
|
||||
# 项目简介
|
||||
|
||||
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、图片等多种格式的智能解析
|
||||
- **权限管理**: 三级权限体系（超级管理员、管理员、普通用户）
|
||||
- **内容安全**: 内置内容审查机制，保障服务合规性
|
||||
|
||||
## 演示视频
|
||||
|
||||
<div align="center">
|
||||
<a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank">
|
||||
<img width="3651" height="1933" alt="视频演示缩略图" src="https://github.com/user-attachments/assets/eac4fa89-2176-46ae-a649-45a125cb6ed1" />
|
||||
</a>
|
||||
<p style="margin-top: 12px;">
|
||||
<a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank" style="text-decoration: none; color: #23ade5; font-weight: 500;">
|
||||
📽️ 点击查看视频演示 <i class="fa fa-external-link" style="margin-left: 4px;"></i>
|
||||
</a>
|
||||
</p>
|
||||
</div>
|
||||
@ -1,59 +1,9 @@
|
||||
# 快速开始指南
|
||||
|
||||
## 项目简介
|
||||
|
||||
Yuxi-Know（语析）是一个基于知识图谱和向量数据库的智能知识库系统，融合了 RAG（检索增强生成）技术与知识图谱技术，为用户提供智能问答和知识管理服务。
|
||||
|
||||
### 技术架构
|
||||
|
||||
- **后端服务**: FastAPI + Python 3.12+
|
||||
- **前端界面**: Vue.js 3 + TypeScript
|
||||
- **知识存储**: Milvus（向量数据库）+ Neo4j（图数据库）
|
||||
- **智能体框架**: LangGraph
|
||||
- **文档解析**: LightRAG + MinerU + PP-Structure-V3
|
||||
- **容器编排**: Docker Compose
|
||||
|
||||
### 核心功能
|
||||
|
||||
- **智能问答**: 支持多种大语言模型，提供智能对话和问答服务
|
||||
- **知识库管理**: 支持多种存储形式（Chroma、Milvus、LightRAG）
|
||||
- **知识图谱**: 自动构建和可视化知识图谱，支持图查询
|
||||
- **文档解析**: 支持 PDF、Word、图片等多种格式的智能解析
|
||||
- **权限管理**: 三级权限体系（超级管理员、管理员、普通用户）
|
||||
- **内容安全**: 内置内容审查机制，保障服务合规性
|
||||
|
||||
## 演示视频
|
||||
|
||||
<div align="center">
|
||||
<a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank">
|
||||
<img width="3651" height="1933" alt="视频演示缩略图" src="https://github.com/user-attachments/assets/eac4fa89-2176-46ae-a649-45a125cb6ed1" />
|
||||
</a>
|
||||
<p style="margin-top: 12px;">
|
||||
<a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank" style="text-decoration: none; color: #23ade5; font-weight: 500;">
|
||||
📽️ 点击查看视频演示 <i class="fa fa-external-link" style="margin-left: 4px;"></i>
|
||||
</a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 系统要求
|
||||
|
||||
#### 硬件要求
|
||||
- **CPU**: 2 核心以上
|
||||
- **内存**: 4GB 以上（推荐 8GB）
|
||||
- **存储**: 10GB 以上可用空间
|
||||
- **网络**: 稳定的互联网连接（用于下载模型和依赖）
|
||||
|
||||
#### 软件要求
|
||||
- **Docker**: 20.10+ 版本
|
||||
- **Docker Compose**: 2.0+ 版本
|
||||
- **操作系统**: Linux、macOS 或 Windows（支持 WSL2）
|
||||
|
||||
#### 可选配置
|
||||
- **GPU**: NVIDIA GPU（用于 OCR 服务和本地模型推理）
|
||||
- **CUDA**: 11.8+ 或 12.6+（根据服务选择）
|
||||
|
||||
::: tip 提示
|
||||
项目采用微服务架构，核心服务无需 GPU 支持。GPU 仅用于可选的 OCR 服务和本地模型推理，可通过环境变量配置外部服务。
|
||||
:::
|
||||
@ -184,515 +134,6 @@ docker restart api-dev
|
||||
</details>
|
||||
|
||||
|
||||
## 模型配置
|
||||
|
||||
### 对话模型
|
||||
|
||||
系统支持多种大语言模型服务商，通过配置对应的 API 密钥即可使用：
|
||||
|
||||
| 服务商 | 环境变量 | 特点 |
|
||||
|--------|----------|------|
|
||||
| 硅基流动 | `SILICONFLOW_API_KEY` | 🆓 免费额度，默认推荐 |
|
||||
| OpenAI | `OPENAI_API_KEY` | GPT 系列模型 |
|
||||
| DeepSeek | `DEEPSEEK_API_KEY` | 国产大模型 |
|
||||
| OpenRouter | `OPENROUTER_API_KEY` | 多模型聚合平台 |
|
||||
| 智谱清言 | `ZHIPUAI_API_KEY` | GLM 系列模型 |
|
||||
| 阿里云百炼 | `DASHSCOPE_API_KEY` | 通义千问系列 |
|
||||
|
||||
#### 自定义模型供应商
|
||||
|
||||
如需添加新的模型供应商，请按以下步骤操作：
|
||||
|
||||
1. 编辑 `src/config/static/models.yaml` 文件
|
||||
2. 在 `.env` 文件中添加对应的环境变量
|
||||
3. 重新部署项目
|
||||
|
||||
**配置示例**：
|
||||
|
||||
```yaml
|
||||
custom-provider-name:
|
||||
name: custom-provider-name
|
||||
default: custom-model-name
|
||||
base_url: "https://api.your-provider.com/v1"
|
||||
env:
|
||||
- CUSTOM_API_KEY_ENV_NAME
|
||||
models:
|
||||
- supported-model-name
|
||||
```
|
||||
|
||||
### 嵌入模型和重排序模型
|
||||
|
||||
::: warning 重要说明
|
||||
从 v0.2 版本开始，项目采用微服务架构，模型部署与项目本身完全解耦。如需使用本地模型，需要先通过 vLLM 或 Ollama 部署为 API 服务。
|
||||
:::
|
||||
|
||||
#### 本地模型部署
|
||||
|
||||
**1. 配置模型信息**
|
||||
|
||||
在 `src/config/static/models.yaml` 或 `src/config/static/models.private.yaml` 中添加配置：
|
||||
|
||||
```yaml
|
||||
EMBED_MODEL_INFO:
|
||||
vllm/Qwen/Qwen3-Embedding-0.6B:
|
||||
name: Qwen/Qwen3-Embedding-0.6B
|
||||
dimension: 1024
|
||||
base_url: http://localhost:8000/v1/embeddings
|
||||
api_key: no_api_key
|
||||
|
||||
RERANKER_LIST:
|
||||
vllm/BAAI/bge-reranker-v2-m3:
|
||||
name: BAAI/bge-reranker-v2-m3
|
||||
base_url: http://localhost:8000/v1/rerank
|
||||
api_key: no_api_key
|
||||
```
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
### OpenAI 兼容模型
|
||||
|
||||
系统理论上兼容任何 OpenAI 兼容的模型服务，包括：
|
||||
|
||||
- **vLLM**: 高性能推理服务
|
||||
- **Ollama**: 本地模型管理
|
||||
- **API 中转服务**: 各种代理和聚合服务
|
||||
|
||||
在 Web 界面的"设置"页面中可以添加本地模型地址。
|
||||
|
||||
|
||||
## 功能详解
|
||||
|
||||
### 知识库管理
|
||||
|
||||
系统支持多种知识库存储形式，满足不同场景需求：
|
||||
|
||||
| 存储类型 | 特点 | 适用场景 |
|
||||
|----------|------|----------|
|
||||
| **Chroma** | 轻量级向量数据库 | 小型项目、快速原型 |
|
||||
| **Milvus** | 高性能向量数据库 | 大规模生产环境 |
|
||||
| **LightRAG** | 图增强检索 | 复杂知识关系 |
|
||||
|
||||
#### 知识库可视化
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><img src="https://github.com/user-attachments/assets/6ad3cc6a-3816-4545-b074-6eeb814d8124" alt="知识图谱可视化"></td>
|
||||
<td><img src="https://github.com/user-attachments/assets/6cc3c3a6-b7c2-4dc3-9678-b97de7835959" alt="知识库可视化"></td>
|
||||
<td><img src="/images/neo4j_browser.png"></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
### 知识图谱
|
||||
|
||||
#### LightRAG 自动构建
|
||||
|
||||
系统支持基于 [LightRAG](https://github.com/HKUDS/LightRAG) 的知识图谱自动构建：
|
||||
|
||||
1. **创建 LightRAG 知识库**: 在知识库管理中选择 LightRAG 类型
|
||||
2. **上传文档**: 系统自动解析文档并构建知识图谱
|
||||
3. **图谱导入**: 构建的图谱自动导入 Neo4j 数据库
|
||||
4. **标签区分**: 使用不同标签区分不同来源的图谱数据
|
||||
|
||||
::: warning 使用限制
|
||||
- LightRAG 知识库可在知识库详情中可视化
|
||||
- 不支持在侧边栏图谱中直接检索
|
||||
- 图谱检索工具不支持 LightRAG 知识库
|
||||
- 查询需要使用对应的知识库作为工具
|
||||
:::
|
||||
|
||||
#### 图谱构建模型
|
||||
|
||||
默认使用 `siliconflow` 的 `Qwen/Qwen3-30B-A3B-Instruct-2507` 模型，可通过环境变量自定义：
|
||||
|
||||
```env
|
||||
LIGHTRAG_LLM_PROVIDER=siliconflow
|
||||
LIGHTRAG_LLM_NAME=Qwen/Qwen3-30B-A3B-Instruct-2507
|
||||
```
|
||||
|
||||
#### 图谱可视化
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>知识图谱可视化</th>
|
||||
<th>知识库可视化</th>
|
||||
<th>Neo4J管理端</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><img src="https://github.com/user-attachments/assets/87b1dc91-65f4-4529-84b3-1b2a561c580d" alt="知识图谱可视化" height="210"></td>
|
||||
<td><img src="https://github.com/user-attachments/assets/452b8228-a59f-4f28-80ce-7d93e9497ccc" alt="知识库可视化" height="210"></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
#### 外部图谱导入
|
||||
|
||||
系统支持导入已有的知识图谱数据到 Neo4j 中：
|
||||
|
||||
**数据格式**: JSONL 格式，每行一个三元组
|
||||
|
||||
```jsonl
|
||||
{"h": "北京", "t": "中国", "r": "首都"}
|
||||
{"h": "上海", "t": "中国", "r": "直辖市"}
|
||||
```
|
||||
|
||||
**导入规则**:
|
||||
- 节点自动添加 `Upload`、`Entity` 标签
|
||||
- 关系自动添加 `Relation` 标签
|
||||
- 通过 `name` 属性访问实体名称
|
||||
- 通过 `type` 属性访问关系名称
|
||||
|
||||
**Neo4j 访问信息**:
|
||||
- 默认账户: `neo4j`
|
||||
- 默认密码: `0123456789`
|
||||
- 管理界面: http://localhost:7474
|
||||
|
||||
::: tip 测试数据
|
||||
可以使用 `test/data/A_Dream_of_Red_Mansions_tiny.jsonl` 文件进行测试导入。
|
||||
:::
|
||||
|
||||
#### 外部 Neo4j 接入
|
||||
|
||||
如需接入已有的 Neo4j 实例，可修改 `docker-compose.yml` 中的 `NEO4J_URI` 配置。
|
||||
|
||||
::: warning 注意事项
|
||||
确保每个节点都有 `Entity` 标签，每个关系都有 `RELATION` 类型，否则会影响图的检索与构建功能。
|
||||
:::
|
||||
|
||||
## 高级配置
|
||||
|
||||
### OCR 服务
|
||||
|
||||
系统提供多种 OCR 服务选项，满足不同精度和性能需求：
|
||||
|
||||
#### 基础 OCR 服务
|
||||
|
||||
使用 RapidOCR ONNX 版本，无需 GPU 支持：
|
||||
|
||||
**1. 下载模型**
|
||||
|
||||
```bash
|
||||
huggingface-cli download SWHL/RapidOCR --local-dir ${MODEL_DIR:-./models}/SWHL/RapidOCR
|
||||
```
|
||||
|
||||
**2. 模型要求**
|
||||
|
||||
确保以下文件存在：
|
||||
- `PP-OCRv4/ch_PP-OCRv4_det_infer.onnx`
|
||||
- `PP-OCRv4/ch_PP-OCRv4_rec_infer.onnx`
|
||||
|
||||
::: warning 权限问题
|
||||
如果提示 `[Errno 13] Permission denied`，需要使用 sudo 修改权限后执行。
|
||||
:::
|
||||
|
||||
#### 高级 OCR 服务
|
||||
|
||||
为提升 PDF 解析准确性，可选择以下 GPU 加速服务：
|
||||
|
||||
**MinerU 服务**（推荐）
|
||||
|
||||
```bash
|
||||
# 需要 CUDA 12.6+ 环境
|
||||
docker compose up mineru --build
|
||||
```
|
||||
|
||||
**PP-Structure-V3 服务**
|
||||
|
||||
```bash
|
||||
# 需要 CUDA 11.8+ 环境
|
||||
docker compose up paddlex --build
|
||||
```
|
||||
|
||||
配置文件位置: `docker/PP-StructureV3.yaml`
|
||||
|
||||
### 智能体开发
|
||||
|
||||
系统基于 [LangGraph](https://github.com/langchain-ai/langgraph) 框架，支持自定义智能体应用开发。
|
||||
|
||||
#### 内置智能体
|
||||
|
||||
系统默认集成三个示例智能体：
|
||||
|
||||
| 智能体 | 功能 | 位置 |
|
||||
|--------|------|------|
|
||||
| **基础智能体** | 简单对话功能 | `src/agents/chatbot/` |
|
||||
| **ReAct 智能体** | 推理与行动循环 | `src/agents/react/` |
|
||||
| **DeepResearch 智能体** | 深度研究分析 | `src/agents/deepresearch/` |
|
||||
|
||||
#### 开发自定义智能体
|
||||
|
||||
**1. 创建智能体类**
|
||||
|
||||
继承 `BaseAgent` 并实现 `get_graph` 方法：
|
||||
|
||||
```python
|
||||
from .base import BaseAgent
|
||||
|
||||
class CustomAgent(BaseAgent):
|
||||
def get_graph(self):
|
||||
# 返回 LangGraph 实例
|
||||
return graph_instance
|
||||
|
||||
@property
|
||||
def context_schema(self):
|
||||
# 定义配置参数
|
||||
return schema
|
||||
```
|
||||
|
||||
**2. 注册智能体**
|
||||
|
||||
在 `src/agents/__init__.py` 中注册：
|
||||
|
||||
```python
|
||||
from .custom_agent import CustomAgent
|
||||
|
||||
agent_manager = AgentManager()
|
||||
agent_manager.register_agent(CustomAgent)
|
||||
agent_manager.init_all_agents()
|
||||
```
|
||||
|
||||
**3. 参考示例**
|
||||
|
||||
查看 `src/agents/react/graph.py` 中的 `ReActAgent` 实现示例。
|
||||
|
||||
### MySQL 数据库集成
|
||||
|
||||
系统支持智能体查询 MySQL 数据库，为数据分析提供强大支持。
|
||||
|
||||
#### 配置数据库连接
|
||||
|
||||
在环境变量中配置数据库信息：
|
||||
|
||||
```env
|
||||
# MySQL 数据库配置
|
||||
MYSQL_HOST=192.168.1.100
|
||||
MYSQL_USER=username
|
||||
MYSQL_PASSWORD=your_secure_password
|
||||
MYSQL_DATABASE=database_name
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_CHARSET=utf8mb4
|
||||
```
|
||||
|
||||
#### 可用工具
|
||||
|
||||
在智能体配置中启用以下 MySQL 工具：
|
||||
|
||||
| 工具名称 | 功能描述 |
|
||||
|----------|----------|
|
||||
| `mysql_list_tables` | 获取数据库中的所有表名 |
|
||||
| `mysql_describe_table` | 获取指定表的详细结构信息 |
|
||||
| `mysql_query` | 执行只读的 SQL 查询语句 |
|
||||
|
||||
#### 安全特性
|
||||
|
||||
- ✅ **只读操作**: 仅允许 SELECT、SHOW、DESCRIBE、EXPLAIN 操作
|
||||
- ✅ **SQL 注入防护**: 严格的表名参数验证
|
||||
- ✅ **超时控制**: 默认 10 秒，最大 60 秒
|
||||
- ✅ **结果限制**: 默认 10000 字符，100 行，最大 1000 行
|
||||
|
||||
#### 使用建议
|
||||
|
||||
1. **权限设置**: 确保数据库用户只有只读权限
|
||||
2. **大表查询**: 建议使用 LIMIT 子句限制结果
|
||||
3. **复杂查询**: 可能需要调整超时时间
|
||||
4. **结果处理**: 查询结果过大会被自动截断并提示
|
||||
|
||||
### 图表可视化 - MCP
|
||||
|
||||
系统支持基于 MCP（Model Context Protocol）的图表可视化功能。
|
||||
|
||||
#### 功能特点
|
||||
|
||||
- 基于 @antvis 团队开发的 [可视化图表-MCP-Server](https://www.modelscope.cn/mcp/servers/@antvis/mcp-server-chart)
|
||||
- 支持多种图表类型和数据可视化
|
||||
- 通过魔搭社区配置 Host 资源
|
||||
|
||||
#### 配置方法
|
||||
|
||||
在 `src/agents/common/mcp.py` 的 `MCP_SERVERS` 中添加配置：
|
||||
|
||||
```python
|
||||
# MCP Server configurations
|
||||
MCP_SERVERS = {
|
||||
"sequentialthinking": {
|
||||
"url": "https://remote.mcpservers.org/sequentialthinking/mcp",
|
||||
"transport": "streamable_http",
|
||||
},
|
||||
"mcp-server-chart": {
|
||||
"url": "https://mcp.api-inference.modelscope.net/9993ae42524c4c/mcp",
|
||||
"transport": "streamable_http",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: warning 配置注意
|
||||
记得将 `type` 字段修改为 `transport`。
|
||||
:::
|
||||
|
||||
### 内容安全
|
||||
|
||||
系统内置内容审查机制，保障服务内容的合规性。
|
||||
|
||||
#### 功能特点
|
||||
|
||||
- **输入过滤**: 对用户输入进行关键词检测
|
||||
- **输出审查**: 对模型生成内容进行安全审查
|
||||
- **实时拦截**: 防止不当内容传播
|
||||
|
||||
#### 配置方法
|
||||
|
||||
管理员可在 `设置` → `基本设置` 页面中：
|
||||
|
||||
- ✅ 一键启用/禁用内容审查功能
|
||||
- ✅ 自定义敏感词词库
|
||||
- ✅ 调整审查策略
|
||||
|
||||
#### 敏感词管理
|
||||
|
||||
敏感词词库位于 `src/config/static/bad_keywords.txt` 文件：
|
||||
|
||||
- 每行一个关键词
|
||||
- 支持自定义修改
|
||||
- 实时生效，无需重启服务
|
||||
|
||||
|
||||
|
||||
### 服务端口
|
||||
|
||||
系统使用多个端口提供不同服务，以下是完整的端口映射：
|
||||
|
||||
| 端口 | 服务 | 容器名称 | 说明 |
|
||||
|------|------|----------|------|
|
||||
| **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
|
||||
:::
|
||||
|
||||
|
||||
### 品牌定制
|
||||
|
||||
系统支持完整的品牌信息自定义，包括 Logo、组织名称、版权信息等。
|
||||
|
||||
#### 配置方法
|
||||
|
||||
**1. 复制模板文件**
|
||||
|
||||
```bash
|
||||
cp src/config/static/info.template.yaml src/config/static/info.local.yaml
|
||||
```
|
||||
|
||||
**2. 编辑品牌信息**
|
||||
|
||||
在 `src/config/static/info.local.yaml` 中配置：
|
||||
|
||||
```yaml
|
||||
# 组织信息
|
||||
organization_name: "您的组织名称"
|
||||
logo_url: "/path/to/your/logo.png"
|
||||
|
||||
# 版权信息
|
||||
copyright: "© 2024 您的组织名称"
|
||||
```
|
||||
|
||||
**3. 环境变量配置**
|
||||
|
||||
或在 `.env` 文件中指定配置文件路径：
|
||||
|
||||
```env
|
||||
YUXI_BRAND_FILE_PATH=src/config/static/info.local.yaml
|
||||
```
|
||||
|
||||
#### 样式定制
|
||||
|
||||
系统配色主要保存在 `web/src/assets/css/base.css` 中：
|
||||
|
||||
- 替换 `--main-*` 相关变量即可改变配色
|
||||
- 支持主题色、辅助色等完整定制
|
||||
- 实时预览，无需重启服务
|
||||
|
||||
::: tip 配置优先级
|
||||
`info.local.yaml` > `info.template.yaml`（默认）
|
||||
:::
|
||||
|
||||
### 批量处理脚本
|
||||
|
||||
系统提供便捷的批量处理脚本，支持文件上传和解析操作。
|
||||
|
||||
#### 文件上传脚本
|
||||
|
||||
使用 `scripts/batch_upload.py upload` 批量上传文件到知识库：
|
||||
|
||||
```bash
|
||||
# 批量上传文档
|
||||
uv run scripts/batch_upload.py upload \
|
||||
--db-id your_kb_id \
|
||||
--directory path/to/your/data \
|
||||
--pattern "*.docx" \
|
||||
--base-url http://127.0.0.1:5050/api \
|
||||
--username your_username \
|
||||
--password your_password \
|
||||
--concurrency 4 \
|
||||
--recursive \
|
||||
--record-file scripts/tmp/batch_processed_files.txt
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
- `--db-id`: 目标知识库 ID
|
||||
- `--directory`: 文件目录路径
|
||||
- `--pattern`: 文件匹配模式
|
||||
- `--concurrency`: 并发处理数量
|
||||
- `--recursive`: 递归处理子目录
|
||||
- `--record-file`: 处理记录文件路径
|
||||
|
||||
#### 文件解析脚本
|
||||
|
||||
使用 `scripts/batch_upload.py trans` 将文件解析为 Markdown：
|
||||
|
||||
```bash
|
||||
# 批量解析文档
|
||||
uv run scripts/batch_upload.py trans \
|
||||
--db-id your_kb_id \
|
||||
--directory path/to/your/data \
|
||||
--output-dir path/to/output_markdown \
|
||||
--pattern "*.docx" \
|
||||
--base-url http://127.0.0.1:5050/api \
|
||||
--username your_username \
|
||||
--password your_password \
|
||||
--concurrency 4 \
|
||||
--recursive
|
||||
```
|
||||
|
||||
**输出结果**: 解析后的 Markdown 文件将保存到指定输出目录。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 服务管理
|
||||
@ -743,25 +184,3 @@ docker restart api-dev
|
||||
- 密码: `0123456789`
|
||||
- 管理界面: http://localhost:7474
|
||||
|
||||
## 参与贡献
|
||||
|
||||
感谢所有贡献者的支持！
|
||||
|
||||
<a href="https://github.com/xerrors/Yuxi-Know/contributors">
|
||||
<img src="https://contributors.nn.ci/api?repo=xerrors/Yuxi-Know" alt="贡献者名单">
|
||||
</a>
|
||||
|
||||
### 如何贡献
|
||||
|
||||
1. **Fork 项目**: 在 GitHub 上 Fork 本项目
|
||||
2. **创建分支**: `git checkout -b feature/amazing-feature`
|
||||
3. **提交更改**: `git commit -m 'Add some amazing feature'`
|
||||
4. **推送分支**: `git push origin feature/amazing-feature`
|
||||
5. **创建 PR**: 在 GitHub 上创建 Pull Request
|
||||
|
||||
### 开发指南
|
||||
|
||||
- 遵循项目代码规范
|
||||
- 添加必要的测试用例
|
||||
- 更新相关文档
|
||||
- 确保所有测试通过
|
||||
|
||||
@ -2,7 +2,8 @@
|
||||
"scripts": {
|
||||
"docs:dev": "vitepress dev docs",
|
||||
"docs:build": "vitepress build docs",
|
||||
"docs:preview": "vitepress preview docs"
|
||||
"docs:preview": "vitepress preview docs",
|
||||
"docs:host": "vitepress dev docs --host"
|
||||
},
|
||||
"dependencies": {
|
||||
"markdown-it-task-checkbox": "^1.0.6",
|
||||
|
||||
@ -1,20 +1,22 @@
|
||||
MODEL_DIR=models
|
||||
SAVE_DIR=saves
|
||||
|
||||
# 模型供应商
|
||||
SILICONFLOW_API_KEY=sk-aeoampticy******bpdsofstmoqnvsmbvql # > <<< 建议配置
|
||||
OPENAI_API_KEY=sk-aslDB5rqOgK******q5K02ZEiRC9ER
|
||||
OPENAI_API_BASE=https://api.openai.com/v1
|
||||
ZHIPUAI_API_KEY=5f41e******71c7bac.UWkl******Sw5Lb
|
||||
DASHSCOPE_API_KEY=sk-787bb2******f4ae859b5
|
||||
DEEPSEEK_API_KEY=sk-5cab6298******b339f7
|
||||
ARK_API_KEY=a022e8d4-******-cb0766bf22e7
|
||||
TOGETHER_API_KEY=tgp_v1_fPjW******irD6zesAn4
|
||||
# region model_provider
|
||||
# 推荐使用硅基流动免费服务
|
||||
SILICONFLOW_API_KEY=
|
||||
|
||||
# 其余可选配置
|
||||
OPENAI_API_KEY=
|
||||
OPENAI_API_BASE=
|
||||
ZHIPUAI_API_KEY=
|
||||
DASHSCOPE_API_KEY=
|
||||
DEEPSEEK_API_KEY=
|
||||
ARK_API_KEY=
|
||||
TOGETHER_API_KEY=
|
||||
# endregion model_provider
|
||||
|
||||
# 功能服务
|
||||
TAVILY_API_KEY=tvly-3gR4ind9******JMOxw3E2LG # <<< 配置网络搜索
|
||||
|
||||
TAVILY_API_KEY=
|
||||
|
||||
# 基础配置示例
|
||||
MYSQL_HOST=192.168.1.100
|
||||
@ -23,3 +25,15 @@ MYSQL_PASSWORD=your_secure_password
|
||||
MYSQL_DATABASE=database_name
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_CHARSET=utf8mb4
|
||||
|
||||
# region lightrag
|
||||
LIGHTRAG_LLM_PROVIDER=
|
||||
LIGHTRAG_LLM_NAME=
|
||||
# endregion lightrag
|
||||
|
||||
|
||||
# region neo4j
|
||||
NEO4J_URI=
|
||||
NEO4J_USERNAME=
|
||||
NEO4J_PASSWORD=
|
||||
# endregion neo4j
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
<template>
|
||||
<div>
|
||||
<a-alert message="自定义模型将在 0.3的稳定版中移除，届时只能通过修改 models.yaml 来添加模型和供应商。" type="warning" />
|
||||
<br>
|
||||
<div class="model-provider-card custom-models-card">
|
||||
<div class="card-header">
|
||||
<h3>自定义模型</h3>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user