From 7c40d6c4218c3eb0fd83f9e09a1939bedca10711 Mon Sep 17 00:00:00 2001 From: Wenjie Zhang Date: Tue, 14 Oct 2025 04:19:52 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=99=BA=E8=83=BD?= =?UTF-8?q?=E4=BD=93=E5=92=8C=E6=96=87=E6=A1=A3=E5=A4=84=E7=90=86=E7=9B=B8?= =?UTF-8?q?=E5=85=B3=E6=96=87=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0=E5=86=85?= =?UTF-8?q?=E7=BD=AE=E5=B7=A5=E5=85=B7=E8=AF=B4=E6=98=8E=E5=8F=8A=E6=94=AF?= =?UTF-8?q?=E6=8C=81=E7=9A=84=E6=96=87=E4=BB=B6=E7=B1=BB=E5=9E=8B**?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/advanced/agents.md | 22 +++++++++--- docs/advanced/document-processing.md | 11 ++++++ docs/changelog/faq.md | 40 ++++++++++++++++++++++ docs/changelog/roadmap.md | 1 + docs/index.md | 4 ++- docs/intro/knowledge-base.md | 42 +++++++++++++++++++---- docs/intro/quick-start.md | 51 ---------------------------- 7 files changed, 109 insertions(+), 62 deletions(-) diff --git a/docs/advanced/agents.md b/docs/advanced/agents.md index 0da1e68c..ee82231d 100644 --- a/docs/advanced/agents.md +++ b/docs/advanced/agents.md @@ -51,10 +51,24 @@ agent_manager.init_all_agents() ## 内置工具与 MCP 集成 +系统默认会为对话/推理智能体注册一组“内置工具”，并根据配置动态启用： -::: warning -文档待完善 -::: +- 知识图谱查询：`query_knowledge_graph` + - 依赖 Neo4j 服务（见 docker-compose 中 `graph`） + - 返回包含三元组的结果，适合图谱关系类问题 +- 网页搜索：`TavilySearch` + - 需要设置 `TAVILY_API_KEY` 才会启用 + - LLM 在需要时自动调用，提供实时网页信息 +- 知识库检索工具：按知识库动态生成 + - 工具名称形如 `query_`；描述来自知识库名称与说明 + - 在工具选择阶段，用描述帮助模型做针对性检索 +- 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`，并确保服务可达。 ::: diff --git a/docs/advanced/document-processing.md b/docs/advanced/document-processing.md index fa497fd5..27c696e8 100644 --- a/docs/advanced/document-processing.md +++ b/docs/advanced/document-processing.md @@ -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 \ - **断点续传**: 支持中断后继续处理 - **日志记录**: 详细记录处理过程 - **结果统计**: 处理完成后显示统计信息 + +更多关于“入库参数、导出数据、支持类型”等，请参阅：介绍 → 知识库与知识图谱 → 文档管理。 diff --git a/docs/changelog/faq.md b/docs/changelog/faq.md index 80cba6c7..b3fa8787 100644 --- a/docs/changelog/faq.md +++ b/docs/changelog/faq.md @@ -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 --directory --username --password

--base-url http://127.0.0.1:5050/api` + - 转 Markdown：`uv run scripts/batch_upload.py trans --db-id --directory

--username --password

` + - 参考：高级配置 → 文档解析 + +- 登录失败被锁定？ + - 多次失败会临时锁定账户，请根据提示等待后重试 + +- 如何查看日志和状态？ + - `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志 diff --git a/docs/changelog/roadmap.md b/docs/changelog/roadmap.md index a20f5ac4..61cd3816 100644 --- a/docs/changelog/roadmap.md +++ b/docs/changelog/roadmap.md @@ -12,6 +12,7 @@ **Next** +- [ ] 修改现有的 ReAct 智能体，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中 - [ ] 添加对于上传文件的支持 - [ ] 知识图谱的上传和可视化，支持属性，标签的展示 - [ ] 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示 diff --git a/docs/index.md b/docs/index.md index b3448665..f8d857dd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,4 +38,6 @@ features: ```sh docker compose up --build -d -``` \ No newline at end of file +``` + +查看端口与服务说明：高级配置 → 其他配置 → 服务端口。 diff --git a/docs/intro/knowledge-base.md b/docs/intro/knowledge-base.md index 91fca87a..f00fc8f7 100644 --- a/docs/intro/knowledge-base.md +++ b/docs/intro/knowledge-base.md @@ -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. 以三元组形式导入 diff --git a/docs/intro/quick-start.md b/docs/intro/quick-start.md index 79384853..69750198 100644 --- a/docs/intro/quick-start.md +++ b/docs/intro/quick-start.md @@ -131,54 +131,3 @@ docker restart api-dev ``` - - -## 常见问题 - -### 服务管理 - -**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`