diff --git a/docker-compose.yml b/docker-compose.yml index 829231f3..df5cbe8a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -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 diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index b0530d42..3776171e 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -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' } ] } ], diff --git a/docs/advanced/agents.md b/docs/advanced/agents.md new file mode 100644 index 00000000..0da1e68c --- /dev/null +++ b/docs/advanced/agents.md @@ -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`。 +::: diff --git a/docs/advanced/branding.md b/docs/advanced/branding.md new file mode 100644 index 00000000..d8ed4b84 --- /dev/null +++ b/docs/advanced/branding.md @@ -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; /* 边框色 */ +} +``` diff --git a/docs/advanced/document-processing.md b/docs/advanced/document-processing.md new file mode 100644 index 00000000..fa497fd5 --- /dev/null +++ b/docs/advanced/document-processing.md @@ -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 文件将保存到指定输出目录。 + +### 脚本功能 + +- **进度跟踪**: 实时显示处理进度 +- **错误处理**: 自动跳过无法处理的文件 +- **断点续传**: 支持中断后继续处理 +- **日志记录**: 详细记录处理过程 +- **结果统计**: 处理完成后显示统计信息 diff --git a/docs/advanced/misc.md b/docs/advanced/misc.md new file mode 100644 index 00000000..7acd1de6 --- /dev/null +++ b/docs/advanced/misc.md @@ -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 +::: diff --git a/docs/changelog/contributing.md b/docs/changelog/contributing.md new file mode 100644 index 00000000..1aa97c17 --- /dev/null +++ b/docs/changelog/contributing.md @@ -0,0 +1,75 @@ +# 参与贡献 + +感谢所有贡献者的支持！ + + + 贡献者名单 + + +## 如何贡献 + +### 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 开源，贡献的代码将遵循相同的许可证。 + diff --git a/docs/changelog/faq.md b/docs/changelog/faq.md new file mode 100644 index 00000000..80cba6c7 --- /dev/null +++ b/docs/changelog/faq.md @@ -0,0 +1,2 @@ +# 常见问题 + diff --git a/docs/changelog/update.md b/docs/changelog/roadmap.md similarity index 74% rename from docs/changelog/update.md rename to docs/changelog/roadmap.md index bce826fc..d6e03836 100644 --- a/docs/changelog/update.md +++ b/docs/changelog/roadmap.md @@ -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**: +## 未来可能会支持 下面的功能**可能**会放在后续版本实现，暂时未定 diff --git a/docs/intro/knowledge-base.md b/docs/intro/knowledge-base.md new file mode 100644 index 00000000..c588856d --- /dev/null +++ b/docs/intro/knowledge-base.md @@ -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` 类型，否则会影响图的检索与构建功能。 +::: \ No newline at end of file diff --git a/docs/intro/model-config.md b/docs/intro/model-config.md new file mode 100644 index 00000000..3324c964 --- /dev/null +++ b/docs/intro/model-config.md @@ -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 界面的对话页面选择对应模型进行测试。 diff --git a/docs/intro/project-overview.md b/docs/intro/project-overview.md new file mode 100644 index 00000000..c9adb0c1 --- /dev/null +++ b/docs/intro/project-overview.md @@ -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、图片等多种格式的智能解析 +- **权限管理**: 三级权限体系（超级管理员、管理员、普通用户） +- **内容安全**: 内置内容审查机制，保障服务合规性 + +## 演示视频 + +
+ + 视频演示缩略图 + +

+ + 📽️ 点击查看视频演示 + +

+
\ No newline at end of file diff --git a/docs/intro/quick-start.md b/docs/intro/quick-start.md index 8ed21845..a69652f7 100644 --- a/docs/intro/quick-start.md +++ b/docs/intro/quick-start.md @@ -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、图片等多种格式的智能解析 -- **权限管理**: 三级权限体系（超级管理员、管理员、普通用户） -- **内容安全**: 内置内容审查机制，保障服务合规性 - -## 演示视频 - -
- - 视频演示缩略图 - -

- - 📽️ 点击查看视频演示 - -

-
## 快速开始 -### 系统要求 - -#### 硬件要求 -- **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 -## 模型配置 - -### 对话模型 - -系统支持多种大语言模型服务商，通过配置对应的 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** | 图增强检索 | 复杂知识关系 | - -#### 知识库可视化 - - - - - - - - - -
知识图谱可视化知识库可视化
- -### 知识图谱 - -#### 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 -``` - -#### 图谱可视化 - - - - - - - - - - - - - - - -
知识图谱可视化知识库可视化Neo4J管理端
知识图谱可视化知识库可视化
- - -#### 外部图谱导入 - -系统支持导入已有的知识图谱数据到 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 -## 参与贡献 - -感谢所有贡献者的支持！ - - - 贡献者名单 - - -### 如何贡献 - -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 - -### 开发指南 - -- 遵循项目代码规范 -- 添加必要的测试用例 -- 更新相关文档 -- 确保所有测试通过 diff --git a/package.json b/package.json index 4a745a2f..728b593e 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/src/.env.template b/src/.env.template index fe253aae..b6dd1a65 100644 --- a/src/.env.template +++ b/src/.env.template @@ -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 diff --git a/web/src/components/ModelProvidersComponent.vue b/web/src/components/ModelProvidersComponent.vue index 4f47e691..75d026ac 100644 --- a/web/src/components/ModelProvidersComponent.vue +++ b/web/src/components/ModelProvidersComponent.vue @@ -1,5 +1,7 @@