ForcePilot/docs/intro/quick-start.md

# 快速开始指南

## 项目简介

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 服务和本地模型推理，可通过环境变量配置外部服务。
:::

### 安装步骤

#### 1. 获取项目代码

```bash
# 克隆稳定版本
git clone -b 0.2.1 https://github.com/xerrors/Yuxi-Know.git
cd Yuxi-Know
```

::: warning 版本说明
- `0.2.1`: 当前稳定版本（推荐）
- `stable`: 旧版本稳定分支（与现版本不兼容）
- `main`: 最新开发版本（可能不稳定）
:::

#### 2. 配置环境变量

复制环境变量模板并编辑：

```bash
cp src/.env.template src/.env
```

编辑 `src/.env` 文件，配置必需的 API 密钥：

```env
# 必需配置 - 推荐使用硅基流动免费服务
SILICONFLOW_API_KEY=sk-270ea********8bfa97.e3XOMd****Q1Sk
```

::: 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
bash docker/pull_image.sh python:3.11-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
export HTTP_PROXY=http://IP:PORT
export HTTPS_PROXY=http://IP:PORT
```

如果已配置代理但构建失败，尝试移除代理后重试。

</details>

<details>
<summary><strong>Milvus 启动失败</strong></summary>

```bash
# 重启 Milvus 服务
docker compose up milvus -d
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>
    </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 文件将保存到指定输出目录。

## 常见问题

### 服务管理

**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

## 参与贡献

感谢所有贡献者的支持！

<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

### 开发指南

- 遵循项目代码规范
- 添加必要的测试用例
- 更新相关文档
- 确保所有测试通过

## 项目信息

### Star History

[![Star History Chart](https://api.star-history.com/svg?repos=xerrors/Yuxi-Know)](https://star-history.com/#xerrors/Yuxi-Know)

### 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

---

<div align="center">

**如果这个项目对您有帮助，请不要忘记给我们一个 ⭐️**

[报告问题](https://github.com/xerrors/Yuxi-Know/issues) | [功能请求](https://github.com/xerrors/Yuxi-Know/issues) | [讨论](https://github.com/xerrors/Yuxi-Know/discussions)

</div>