docs: 更新智能体和文档处理相关文档，添加内置工具说明及支持的文件类型**
This commit is contained in:
Wenjie Zhang
parent
e4d5bc6cd3
commit
7c40d6c421
@ -51,10 +51,24 @@ agent_manager.init_all_agents()
|
||||
|
||||
## 内置工具与 MCP 集成
|
||||
|
||||
系统默认会为对话/推理智能体注册一组“内置工具”，并根据配置动态启用：
|
||||
|
||||
::: warning
|
||||
文档待完善
|
||||
:::
|
||||
- 知识图谱查询：`query_knowledge_graph`
|
||||
- 依赖 Neo4j 服务（见 docker-compose 中 `graph`）
|
||||
- 返回包含三元组的结果，适合图谱关系类问题
|
||||
- 网页搜索：`TavilySearch`
|
||||
- 需要设置 `TAVILY_API_KEY` 才会启用
|
||||
- LLM 在需要时自动调用，提供实时网页信息
|
||||
- 知识库检索工具：按知识库动态生成
|
||||
- 工具名称形如 `query_<db_id前缀>`；描述来自知识库名称与说明
|
||||
- 在工具选择阶段，用描述帮助模型做针对性检索
|
||||
- MySQL 工具包：只读查询
|
||||
- `mysql_list_tables`、`mysql_describe_table`、`mysql_query`
|
||||
- 环境变量见下，具备超时/行数限制与注入防护
|
||||
|
||||
MCP（Model Context Protocol）可接入外部可视化或其他工具能力：
|
||||
- 在 `src/agents/common/mcp.py` 的 `MCP_SERVERS` 添加配置；`transport` 字段名必须正确
|
||||
- 常见问题：无法列出工具多因服务不可达或配置错误；优先检查可达性与字段名
|
||||
|
||||
|
||||
### 1. MySQL 数据库集成
|
||||
@ -115,5 +129,5 @@ MCP_SERVERS = {
|
||||
```
|
||||
|
||||
::: warning 配置注意
|
||||
记得将 `type` 字段修改为 `transport`。
|
||||
记得将 `type` 字段修改为 `transport`，并确保服务可达。
|
||||
:::
|
||||
|
||||
@ -51,6 +51,13 @@ docker compose up paddlex --build
|
||||
- **结构化文档**: PP-Structure-V3
|
||||
- **生产环境**: 根据硬件条件选择
|
||||
|
||||
### `enable_ocr` 取值说明（入库参数）
|
||||
|
||||
- `disable`：不启用 OCR（PDF 将按纯文本提取，图片会自动转为 `onnx_rapid_ocr` 提示）
|
||||
- `onnx_rapid_ocr`：CPU 友好，安装简单
|
||||
- `mineru_ocr`：GPU 加速，复杂文档效果好
|
||||
- `paddlex_ocr`：结构化表格/票据等场景
|
||||
|
||||
## 批量处理脚本
|
||||
|
||||
系统提供便捷的批量处理脚本，支持文件上传和解析操作。
|
||||
@ -81,6 +88,8 @@ uv run scripts/batch_upload.py upload \
|
||||
- `--recursive`: 递归处理子目录
|
||||
- `--record-file`: 处理记录文件路径
|
||||
|
||||
提示：系统按“内容哈希”进行去重；同一知识库已存在相同内容的文件会被拒绝（409）。
|
||||
|
||||
### 文件解析脚本
|
||||
|
||||
使用 `scripts/batch_upload.py trans` 将文件解析为 Markdown：
|
||||
@ -108,3 +117,5 @@ uv run scripts/batch_upload.py trans \
|
||||
- **断点续传**: 支持中断后继续处理
|
||||
- **日志记录**: 详细记录处理过程
|
||||
- **结果统计**: 处理完成后显示统计信息
|
||||
|
||||
更多关于“入库参数、导出数据、支持类型”等，请参阅：介绍 → 知识库与知识图谱 → 文档管理。
|
||||
|
||||
@ -1,2 +1,42 @@
|
||||
# 常见问题
|
||||
|
||||
以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。
|
||||
|
||||
- 首次运行如何创建管理员？
|
||||
- Web 首次启动会引导初始化；也可调用 API：
|
||||
- `GET /api/auth/check-first-run` → `first_run=true` 时
|
||||
- `POST /api/auth/initialize` 提交 `user_id` 与 `password`
|
||||
- 无默认账号，初始化后使用创建的超级管理员登录
|
||||
|
||||
- 镜像拉取/构建失败？
|
||||
- 可使用 `docker/pull_image.sh` 辅助拉取，或配置代理环境变量 `HTTP_PROXY/HTTPS_PROXY`
|
||||
- 若已配置代理仍失败，可临时取消代理后重试
|
||||
- 参考：介绍 → 快速开始 → 故障排除
|
||||
|
||||
- 服务端口与访问地址？
|
||||
- Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs`
|
||||
- 端口一览与说明见：高级配置 → 其他配置 → 服务端口
|
||||
|
||||
- Milvus/Neo4j 启动或连接失败？
|
||||
- 重启：`docker compose up milvus -d && docker restart api-dev`
|
||||
- Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474`
|
||||
|
||||
- OCR 模型或服务不可用？
|
||||
- RapidOCR 本地模型：确保 `MODEL_DIR/SWHL/RapidOCR` 下存在 `PP-OCRv4` 模型
|
||||
- MinerU/PaddleX：检查健康检查接口与 GPU/CUDA 版本
|
||||
- 参考：高级配置 → 文档解析
|
||||
|
||||
- 支持的文件类型与常见入库失败？
|
||||
- 查询：`GET /api/knowledge/files/supported-types`
|
||||
- 常见失败：不支持的扩展名、内容哈希重复（去重）、OCR 服务未就绪
|
||||
|
||||
- 批量上传与转换示例？
|
||||
- 上传入库：`uv run scripts/batch_upload.py upload --db-id <id> --directory <dir> --username <u> --password <p> --base-url http://127.0.0.1:5050/api`
|
||||
- 转 Markdown：`uv run scripts/batch_upload.py trans --db-id <id> --directory <dir> --username <u> --password <p>`
|
||||
- 参考：高级配置 → 文档解析
|
||||
|
||||
- 登录失败被锁定？
|
||||
- 多次失败会临时锁定账户，请根据提示等待后重试
|
||||
|
||||
- 如何查看日志和状态？
|
||||
- `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志
|
||||
|
||||
@ -12,6 +12,7 @@
|
||||
|
||||
**Next**
|
||||
|
||||
- [ ] 修改现有的 ReAct 智能体，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中
|
||||
- [ ] 添加对于上传文件的支持
|
||||
- [ ] 知识图谱的上传和可视化，支持属性，标签的展示 <Badge type="info" text="0.4" />
|
||||
- [ ] 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示
|
||||
|
||||
@ -38,4 +38,6 @@ features:
|
||||
|
||||
```sh
|
||||
docker compose up --build -d
|
||||
```
|
||||
```
|
||||
|
||||
查看端口与服务说明：高级配置 → 其他配置 → 服务端口。
|
||||
|
||||
@ -33,15 +33,45 @@ LightRAG 知识库可在知识库详情中可视化，但不支持在侧边栏
|
||||
|
||||
## 文档管理
|
||||
|
||||
::: danger
|
||||
待补充
|
||||
:::
|
||||
本系统的“上传 → 解析入库 → 检索/可视化”流程既可通过 Web 界面完成，也可使用 API/脚本批量处理。
|
||||
|
||||
**支持的文件类型**
|
||||
|
||||
- 文本与文档：`.txt`、`.md`、`.doc`、`.docx`、`.pdf`
|
||||
- 网页与数据：`.html`、`.htm`、`.json`、`.csv`、`.xls`、`.xlsx`
|
||||
- 图片：`.jpg`、`.jpeg`、`.png`、`.bmp`、`.tiff`、`.tif`
|
||||
|
||||
接口查询：`GET /api/knowledge/files/supported-types`
|
||||
|
||||
**上传与入库**
|
||||
|
||||
1) 上传文件（返回服务端保存路径）
|
||||
- `POST /api/knowledge/files/upload?db_id=<可选>`
|
||||
- 成功返回：`file_path`（后续入库使用）、`content_hash`（内容去重）
|
||||
|
||||
2) 解析并入库（异步任务）
|
||||
- `POST /api/knowledge/databases/{db_id}/documents`
|
||||
- 返回：`status=queued` 与 `task_id`，可在任务中心查看进度
|
||||
|
||||
去重策略：系统按“内容哈希”判断是否已存在相同文件，避免重复入库。
|
||||
|
||||
### 批量脚本
|
||||
|
||||
- 上传并入库：参见 `scripts/batch_upload.py upload`
|
||||
- 转换为 Markdown：参见 `scripts/batch_upload.py trans`
|
||||
|
||||
## 知识图谱
|
||||
|
||||
::: danger
|
||||
待补充关于知识图谱在项目中的定位
|
||||
:::
|
||||
本项目存在两类“图谱相关”能力：
|
||||
|
||||
- 全局知识图谱（Neo4j）：用于智能体工具 `query_knowledge_graph` 的图实体查询；统一保存在 Neo4j 中，提供三元组检索和系统级可视化。
|
||||
- LightRAG 知识库内图谱：针对某个知识库由 LightRAG 自动抽取实体/关系，用于该库内的图增强检索与可视化；与全局图共享同一 Neo4j 实例，但通过特殊 tag 区分，不作为全局图谱使用。
|
||||
|
||||
选择建议：
|
||||
- 更结构化的库内检索/可视化：优先使用 LightRAG（注意构建质量与成本）。
|
||||
- 统一的图查询/工具调用：依赖全局 Neo4j 图谱与工具 `query_knowledge_graph`。
|
||||
|
||||
接入已有 Neo4j 实例、三元组导入方式与注意事项见下文说明；LightRAG 构建模型可通过 `.env` 中的 `LIGHTRAG_LLM_*` 变量覆盖。
|
||||
|
||||
### 1. 以三元组形式导入
|
||||
|
||||
|
||||
@ -131,54 +131,3 @@ docker restart api-dev
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 服务管理
|
||||
|
||||
**Q: 如何查看后端服务日志？**
|
||||
|
||||
```bash
|
||||
# 查看后端日志
|
||||
docker logs api-dev -f
|
||||
|
||||
# 查看前端日志
|
||||
docker logs web-dev -f
|
||||
|
||||
# 查看所有服务状态
|
||||
docker ps
|
||||
```
|
||||
|
||||
### OCR 服务
|
||||
|
||||
**Q: RapidOCR 模型未找到怎么办？**
|
||||
|
||||
确认以下文件存在：
|
||||
- `MODEL_DIR` 指向的目录存在 `SWHL/RapidOCR`
|
||||
- 包含 `PP-OCRv4` 下的 `det_infer.onnx` 和 `rec_infer.onnx` 文件
|
||||
|
||||
**Q: MinerU/PaddleX 健康检查失败？**
|
||||
|
||||
分别检查服务状态：
|
||||
- MinerU: `http://localhost:30000/health`
|
||||
- PaddleX: `http://localhost:8080/`
|
||||
|
||||
确认 GPU/驱动与 CUDA 版本匹配。
|
||||
|
||||
### 数据库连接
|
||||
|
||||
**Q: Milvus 启动失败？**
|
||||
|
||||
```bash
|
||||
# 重启 Milvus 服务
|
||||
docker compose up milvus -d
|
||||
docker restart api-dev
|
||||
```
|
||||
|
||||
**Q: Neo4j 连接问题？**
|
||||
|
||||
检查默认账户信息：
|
||||
- 用户名: `neo4j`
|
||||
- 密码: `0123456789`
|
||||
- 管理界面: `http://localhost:7474`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user