chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,83 @@
|
||||
# 命令行工具
|
||||
|
||||
`yuxi-cli` 是 Yuxi 的命令行客户端，适合在本地脚本或终端中管理远程实例、登录账号、上传知识库文件，以及运行部分智能体任务。
|
||||
|
||||
## 安装
|
||||
|
||||
推荐使用 `uv` 或 `pipx` 安装：
|
||||
|
||||
```bash
|
||||
uv tool install yuxi-cli
|
||||
```
|
||||
|
||||
也可以临时运行：
|
||||
|
||||
```bash
|
||||
uvx --from yuxi-cli yuxi --help
|
||||
```
|
||||
|
||||
安装后可通过 `yuxi --version` 查看当前版本。
|
||||
|
||||
## 配置远程实例
|
||||
|
||||
先添加一个 Yuxi 实例地址，再设为当前默认 remote：
|
||||
|
||||
```bash
|
||||
yuxi remote add local http://localhost:5173
|
||||
yuxi remote use local
|
||||
yuxi remote ping
|
||||
```
|
||||
|
||||
配置会保存在 `~/.yuxi/config.toml`。如果需要同时管理多个实例，可以继续添加其他 remote，并通过 `yuxi remote use <name>` 切换。
|
||||
|
||||
## 登录
|
||||
|
||||
默认使用浏览器授权登录：
|
||||
|
||||
```bash
|
||||
yuxi login --browser
|
||||
```
|
||||
|
||||
如果已经在 Yuxi 中创建了 API Key，也可以直接导入：
|
||||
|
||||
```bash
|
||||
yuxi login --api-key yxkey_xxx
|
||||
```
|
||||
|
||||
常用账号状态命令：
|
||||
|
||||
```bash
|
||||
yuxi whoami
|
||||
yuxi status
|
||||
yuxi logout
|
||||
```
|
||||
|
||||
## 上传知识库文件
|
||||
|
||||
上传目录时，如果不指定 `--kb-id`，CLI 会拉取当前 remote 中可用的知识库并在终端中选择：
|
||||
|
||||
```bash
|
||||
yuxi kb upload ./docs
|
||||
```
|
||||
|
||||
默认会选择常见文本和 Office 文档类型，可在预览阶段调整文件类型；也可以通过参数直接指定：
|
||||
|
||||
```bash
|
||||
yuxi kb upload ./docs --kb-id kb_xxx --concurrency 4
|
||||
yuxi kb upload ./docs --include-ext md,html,docx
|
||||
```
|
||||
|
||||
CLI 会让每个并发单元完成单个文件的上传和文档记录添加，`--concurrency` 默认 10，允许范围 1-300，用于控制同时处理的文件数。上传会保留目录中的相对路径，便于在知识库文件列表中按原目录结构查看。
|
||||
|
||||
## 运行智能体评估
|
||||
|
||||
如果实例已配置 Langfuse 数据集，可以用 CLI 触发智能体评估：
|
||||
|
||||
```bash
|
||||
yuxi agent eval \
|
||||
--dataset-name demo-dataset \
|
||||
--agent-slug default-agent \
|
||||
--experiment-name cli-demo
|
||||
```
|
||||
|
||||
该命令会读取 Langfuse 数据集输入，调用 Yuxi 智能体运行，并把结果回传到对应实验中。
|
||||
@@ -0,0 +1,83 @@
|
||||
# 知识库评估指南
|
||||
|
||||
知识库评估是 RAG 系统开发中的重要环节。通过量化评估，我们可以了解检索和生成的质量，发现问题并持续优化。
|
||||
|
||||
## 为什么需要评估
|
||||
|
||||
在构建知识库系统时，你可能会遇到这些问题：
|
||||
|
||||
- 检索结果不准确，用户找不到想要的内容
|
||||
- 生成答案与文档不符，存在幻觉
|
||||
- 调整了分块策略或模型，效果是变好还是变差了？
|
||||
|
||||
评估功能就是为了回答这些问题。它通过预设的测试问题和标准答案，量化系统的表现，帮助你做出数据驱动的优化决策。
|
||||
|
||||
## 评估指标解读
|
||||
|
||||
系统提供以下核心指标：
|
||||
|
||||
| 指标 | 含义 | 参考值 |
|
||||
|------|------|--------|
|
||||
| Recall@1 | 第一个检索结果包含正确文档的比例 | > 0.6 为佳 |
|
||||
| Recall@5 | 前5个检索结果包含正确文档的比例 | > 0.8 为佳 |
|
||||
| F1@K | 精确率和召回率的调和平均 | 用于横向对比 |
|
||||
| 答案准确性 | 生成答案与标准答案的一致性 | 越高越好 |
|
||||
|
||||
## 创建评估基准
|
||||
|
||||
### 手动准备数据
|
||||
|
||||
准备 JSONL 格式的评估文件，每行一个样本：
|
||||
|
||||
```json
|
||||
{"query": "什么是人工智能？", "gold_chunk_ids": ["chunk_001"], "gold_answer": "人工智能是..."}
|
||||
{"query": "机器学习有哪些类型？", "gold_chunk_ids": ["chunk_005"], "gold_answer": "主要包括监督学习..."}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
- `query`：测试问题，必需
|
||||
- `gold_chunk_ids`：期望被检索到的文档块 ID，可选
|
||||
- `gold_answer`：标准答案，用于评估生成质量，可选
|
||||
|
||||
JSONL 只是导入和导出的交换格式。导入后，系统会把评估数据集、题目、评估运行和逐题结果保存到数据库中，不依赖本地 JSONL 文件作为内部存储。
|
||||
|
||||
::: tip 推荐工具
|
||||
可以使用 [EasyDataset](https://github.com/ConardLi/easy-dataset) 从文档批量生成问答对。注意导出时将字段名改为 `query` 和 `gold_answer`。
|
||||
:::
|
||||
|
||||
### 自动生成
|
||||
|
||||
系统也支持自动生成评估数据：随机采样知识库中的文档块，用嵌入模型查找相似内容，最后用大模型生成问答对。
|
||||
|
||||
推荐参数：
|
||||
- 问题数量：10-50 个
|
||||
- 相似文档数：2-5 个
|
||||
- 构建并发数：默认 10，最大 20；模型服务限流较严格时可调低
|
||||
|
||||
## 运行评估
|
||||
|
||||
在知识库详情页左侧边栏，「评估基准」Tab 用于管理评估数据集，「RAG 评估」Tab 用于运行评估并查看结果。在「RAG 评估」中填写评估名称、选择评估数据集后配置：
|
||||
|
||||
1. **答案生成模型**（可选）：基于检索到的文档块生成答案
|
||||
2. **评判模型**（可选）：评估生成答案与标准答案的一致性
|
||||
|
||||
点击「开始评估」，系统在后台执行，完成后会显示各项指标结果。
|
||||
|
||||
## 评估结果分析
|
||||
|
||||
拿到评估结果后，可以从以下几个角度分析：
|
||||
|
||||
- **Recall@1 低**：说明最相关的内容没有被首先检索到，可能需要调整嵌入模型或分块策略
|
||||
- **Recall@5 低**：说明相关文档没有被检索到，可能需要增加检索数量或优化查询
|
||||
- **答案准确性低**：说明生成质量有问题，可能需要调整提示词或更换模型
|
||||
|
||||
## 使用场景
|
||||
|
||||
- **上线前验证**：知识库建设完成后，评估效果是否满足要求
|
||||
- **配置对比**：调整分块策略、嵌入模型后，对比评估结果
|
||||
- **定期监控**：定期评估，及时发现质量下降
|
||||
- **参数调优**：通过多次评估找到最优参数组合
|
||||
|
||||
---
|
||||
|
||||
评估是一个持续的过程。建议在初始建设时就建立评估基准，后续每次重大变更都进行评估，形成数据驱动的优化闭环。
|
||||
@@ -0,0 +1,118 @@
|
||||
# 知识库与知识图谱
|
||||
|
||||
Yuxi 提供文档知识库、向量检索、知识导图和知识图谱构建能力。当前支持 Milvus 知识库、Milvus 知识库内的图谱构建/展示/检索，以及 Dify Dataset、Notion Data Source 只读检索。
|
||||
|
||||
## 为什么需要知识库
|
||||
|
||||
在大模型应用场景中，仅依靠模型的内部知识往往不够准确和全面。通过构建知识库，我们可以：
|
||||
|
||||
- **注入私有知识**：让模型能够回答基于私有文档的问题
|
||||
- **降低幻觉**：回答内容可追溯到原始文档
|
||||
- **知识复用**：一次上传，多轮对话中重复使用
|
||||
|
||||
## 知识库类型
|
||||
|
||||
| 类型 | 特点 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| **Milvus** | 高性能向量检索，支持文档入库、检索测试、知识导图、评估和知识图谱构建 | 自建文档知识库与生产检索 |
|
||||
| **Dify** | 连接 Dify Dataset 检索 API，只读连接器 | 复用已有 Dify 数据集 |
|
||||
| **Notion** | 连接 Notion Data Source 检索 API，只读连接器 | 复用已有 Notion 页面内容 |
|
||||
|
||||
只读连接器（Dify、Notion）仅用于检索，不支持上传与入库；历史 LightRAG 类型不再作为受支持类型展示或创建。
|
||||
|
||||
## 创建知识库
|
||||
|
||||
访问 Web 界面的「知识库」页面，点击「新建知识库」：
|
||||
|
||||
1. 填写知识库名称和描述
|
||||
2. 选择知识库类型（Milvus、Dify 或 Notion）
|
||||
3. Milvus 配置嵌入模型和分块策略；只读连接器（Dify、Notion）按类型动态渲染连接参数（如 API URL、Token、Dataset ID 等）
|
||||
4. 配置访问权限
|
||||
5. 保存
|
||||
|
||||
::: tip 提示
|
||||
知识库的名称和描述会被智能体用来判断何时应该使用这个知识库进行检索，所以请尽量详细地描述。
|
||||
:::
|
||||
|
||||
## 文件处理流程
|
||||
|
||||
Milvus 文件从上传到可检索，经历三个阶段：
|
||||
|
||||
### 1. 上传阶段
|
||||
|
||||
将本地文件上传到服务器。文件保持原始格式存储。
|
||||
|
||||
### 2. 解析阶段
|
||||
|
||||
系统将文件转换为 Markdown 格式：
|
||||
|
||||
- 提取文本内容
|
||||
- 图片上传到 MinIO，并在 Markdown 中用 URL 引用
|
||||
- 表格、公式等尽量保持结构化
|
||||
|
||||
### 3. 入库阶段
|
||||
|
||||
系统对 Markdown 内容进行分块，将 chunk 内容与元数据双写到 PostgreSQL 的 `knowledge_chunks` 表，并将向量写入 Milvus。
|
||||
|
||||
在前端界面中，默认会自动完成前两个阶段。如果需要自动入库，勾选「上传后自动入库」选项；否则需要手动点击入库按钮。
|
||||
|
||||
## 知识导图与示例问题
|
||||
|
||||
Milvus 知识库详情页提供「知识导图」Tab，用来把知识库文件列表整理成层次化结构。生成时，后端会读取当前知识库的文件元数据，把文件名和类型交给默认模型生成 JSON 树，并保存到知识库的 `mindmap` 字段。文件数量较多时，当前实现最多取前 20 个文件参与生成，避免一次提示词过长。Agent 运行时也可以通过 `get_mindmap` 工具读取这份结构，用来快速判断知识库大致包含哪些资料。
|
||||
|
||||
导图支持增量更新：详情页的「增量更新」按钮会先调用 `GET /api/knowledge/databases/{kb_id}/mindmap/diff` 检测当前文件列表与已追踪文件之间的变化，再通过 `POST /api/knowledge/databases/{kb_id}/mindmap/generate?incremental=true` 仅处理新增/删除的文件。纯删除场景不需要 AI 调用，直接对现有树做递归手术；新增文件时由 AI 整合进现有分类结构。单文件删除与批量删除接口成功后也会同步移除导图快照中对应的叶子节点，不需要再手动触发增量更新。
|
||||
|
||||
知识库还支持生成示例问题。该能力会基于文件列表生成适合检索测试的问题，并保存到 `sample_questions` 字段；前端检索测试区域会优先使用这些问题作为查询示例。示例问题只依赖文件元数据，不等同于对每个文档全文做总结；如果要在对话中围绕具体内容回答，仍应通过 `query_kb`、`find_kb_document` 和 `open_kb_document` 检索原始 chunk 或文档片段。
|
||||
|
||||
## 知识库权限控制
|
||||
|
||||
每个知识库可以配置独立的访问权限：
|
||||
|
||||
- **全局共享**：所有用户可访问
|
||||
- **部门共享**：指定部门可访问，且必须包含当前用户所在部门
|
||||
- **指定人**：仅创建者、管理员及被明确授权的人员可访问
|
||||
|
||||
权限规则：
|
||||
|
||||
- 超级管理员可访问所有知识库
|
||||
- 管理员可访问共享知识库和本部门的知识库
|
||||
- 普通用户只能访问已授权的知识库
|
||||
|
||||
## 知识图谱
|
||||
|
||||
Milvus 知识库详情页提供「知识图谱」Tab。图谱构建流程会从已入库 chunks 中抽取实体和关系，将 entity/triple 本体与 chunk 引用写入 Neo4j 和 PostgreSQL，并为唯一实体/三元组建立 Milvus 语义索引；检索时可召回图谱实体与三元组，并与 chunk 命中结果融合（RRF）。
|
||||
|
||||
主要能力：
|
||||
|
||||
- 配置 LLM 抽取器，更多抽取方式拓展中
|
||||
- 构建待索引 chunks 的图谱实体与关系
|
||||
- 查看构建状态、标签和统计信息
|
||||
- 在知识库详情页搜索和展示子图
|
||||
- 重置图谱配置与已构建数据
|
||||
|
||||
Neo4j 仍作为 Milvus 图谱存储服务保留，但不再提供独立 `/graph` 前端页面，也不再支持上传 JSONL 三元组到默认全局图谱。
|
||||
|
||||
### Neo4j 配置
|
||||
|
||||
Neo4j 连接信息可以在 `.env` 中配置：
|
||||
|
||||
- 默认账户：`neo4j`
|
||||
- 默认密码：`0123456789`
|
||||
- 管理界面：http://localhost:7474
|
||||
- 连接地址：bolt://localhost:7687
|
||||
|
||||
## API 使用
|
||||
|
||||
如果需要通过程序批量处理文件，可以使用以下接口：
|
||||
|
||||
```bash
|
||||
# 1. 上传文件
|
||||
POST /api/knowledge/files/upload?kb_id=<知识库ID>
|
||||
# 返回 file_path 和 content_hash
|
||||
|
||||
# 2. 解析并入库
|
||||
POST /api/knowledge/databases/{kb_id}/documents
|
||||
# 返回 status=queued 和 task_id
|
||||
```
|
||||
|
||||
系统会自动去重：基于内容哈希判断是否已存在相同文件。
|
||||
@@ -0,0 +1,101 @@
|
||||
# 模型配置
|
||||
|
||||
## 概述
|
||||
|
||||
系统统一通过 **智能体管理 → 模型供应商** 页面管理所有模型（对话模型、嵌入模型、重排模型），无需修改配置文件。
|
||||
|
||||
## 配置路径
|
||||
|
||||
```
|
||||
智能体管理 → 模型供应商
|
||||
```
|
||||
|
||||
模型供应商页签仅管理员可见。如果当前账号不是管理员，只能看到普通的智能体管理和个人设置入口。
|
||||
|
||||
## API 凭证配置
|
||||
|
||||
支持两种凭证配置方式：
|
||||
|
||||
| 方式 | 适用场景 |
|
||||
|------|----------|
|
||||
| 环境变量 | 生产环境或不愿在界面暴露 Key 的场景 |
|
||||
| 直接填写 | 开发调试，追求配置便利性 |
|
||||
|
||||
**环境变量方式**：在供应商配置中填写变量名（如 `SILICONFLOW_API_KEY`），确保运行时环境已配置对应变量。
|
||||
|
||||
**直接填写方式**：在供应商配置中直接填入 API Key。
|
||||
|
||||
## 供应商管理
|
||||
|
||||
### 内置供应商模板
|
||||
|
||||
系统启动时会同步一组内置 provider 模板。模板只提供 Provider ID、Base URL、凭证环境变量和远端模型发现地址；实际是否可用仍取决于你是否配置凭证、启用供应商并添加模型。
|
||||
|
||||
| 供应商 | Provider ID | 支持类型 | 凭证环境变量 |
|
||||
|--------|-------------|----------|--------------|
|
||||
| OpenAI | `openai` | chat | `OPENAI_API_KEY` |
|
||||
| DeepSeek | `deepseek` | chat | `DEEPSEEK_API_KEY` |
|
||||
| DashScope | `alibaba` | chat, embedding, rerank | `DASHSCOPE_API_KEY` |
|
||||
| Aliyun Coding Plan | `alibaba-coding-plan-cn` | chat | `DASHSCOPE_API_KEY` |
|
||||
| Aliyun Coding Plan International | `alibaba-coding-plan` | chat | `DASHSCOPE_API_KEY` |
|
||||
| Zhipu BigModel | `zhipuai` | chat | `ZHIPUAI_API_KEY` |
|
||||
| Zhipu BigModel Coding Plan | `zhipuai-coding-plan` | chat | `ZHIPUAI_API_KEY` |
|
||||
| Z.AI | `zai` | chat | `ZAI_API_KEY` |
|
||||
| Z.AI Coding Plan | `zai-coding-plan` | chat | `ZAI_API_KEY` |
|
||||
| XiaomiMiMo Token Plan | `xiaomi-token-plan-cn` | chat | `XIAOMI_MIMO_TOKEN_PLAN_API_KEY` |
|
||||
| XiaomiMiMo | `xiaomi` | chat | `XIAOMI_MIMO_API_KEY` |
|
||||
| Kimi Code | `kimi-for-coding` | chat | `KIMI_CODE_API_KEY` |
|
||||
| Moonshot | `moonshotai-cn` | chat | `MOONSHOT_API_KEY` |
|
||||
| Moonshot International | `moonshotai` | chat | `MOONSHOT_API_KEY` |
|
||||
| MiniMax | `minimax-cn` | chat | `MINIMAX_API_KEY` |
|
||||
| MiniMax International | `minimax` | chat | `MINIMAX_API_KEY` |
|
||||
| OpenRouter | `openrouter` | chat, embedding | `OPENROUTER_API_KEY` |
|
||||
| ModelScope | `modelscope` | chat | `MODELSCOPE_ACCESS_TOKEN` |
|
||||
| OpenCode | `opencode` | chat | 无默认环境变量 |
|
||||
| SiliconFlow | `siliconflow-cn` | chat, embedding, rerank | `SILICONFLOW_API_KEY` |
|
||||
| SiliconFlow International | `siliconflow` | chat, embedding, rerank | `SILICONFLOW_GLOBAL_API_KEY` |
|
||||
|
||||
其中 `alibaba`、`siliconflow-cn` 预置了部分 embedding / rerank 模型；其他供应商通常需要进入详情页通过「获取远程模型」或「手动添加」补充模型。
|
||||
|
||||
### 操作流程
|
||||
|
||||
1. **新增供应商**：点击「新增供应商」，填写基本信息（Provider ID、Base URL 等）
|
||||
2. **配置凭证**：填写 API Key 或环境变量名
|
||||
3. **启用供应商**：开启供应商状态开关
|
||||
4. **获取模型**：进入供应商详情，点击「获取远程模型」从 API 拉取可用模型列表
|
||||
|
||||
## 模型管理
|
||||
|
||||
### 添加模型
|
||||
|
||||
**方式一：从远端拉取**
|
||||
|
||||
进入供应商详情 → 点击「获取远程模型」→ 从候选列表中选择添加
|
||||
|
||||
**方式二：手动添加**
|
||||
|
||||
进入供应商详情 → 点击「手动添加」→ 填写模型 ID 和类型
|
||||
|
||||
### 配置参数
|
||||
|
||||
嵌入模型（embedding）需配置向量维度，请参考模型提供商的规格说明。
|
||||
|
||||
### 移除模型
|
||||
|
||||
在供应商详情的已启用模型列表中移除不需要的模型。
|
||||
|
||||
## 模型标识格式
|
||||
|
||||
运行时模型统一使用 `provider_id:model_id` 格式，例如 `siliconflow-cn:Pro/BAAI/bge-m3`。`model_id` 可以包含 `/`，系统只按第一个 `:` 区分供应商与模型 ID。
|
||||
|
||||
旧版 `provider/model`、旧版知识库 JSON 模型字段、配置文件中的 `model_names` / `embed_model_names` / `reranker_names` 不再作为运行时模型来源。历史知识库或 Agent 配置如果仍保存旧格式，需要在界面中重新选择新版模型后保存。
|
||||
|
||||
## Ollama 支持
|
||||
|
||||
当前版本不再内置 Ollama provider type，也不再提供 Ollama embedding 运行时适配。已有 Ollama embedding 知识库需要管理员选择新的 embedding 模型并重建索引，避免不同向量空间混用。
|
||||
|
||||
## 常见问题
|
||||
|
||||
**凭证缺失警告**：检查 API Key 是否正确配置，或确认环境变量是否已设置。
|
||||
|
||||
**模型配置未生效**：确认模型已添加至供应商的已启用列表中。
|
||||
@@ -0,0 +1,78 @@
|
||||
# 项目简介
|
||||
|
||||
Yuxi (语析) 是一个智能知识库和知识图谱 Agent 开发平台，能够帮助你构建结合检索增强生成 (RAG) 与知识图谱推理的生产级 AI 应用。该平台基于 LangGraph、Vue.js 3、FastAPI、Milvus 和 Neo4j 构建，提供创建对话式 AI 系统所需的智能体编排、知识检索、图谱推理、工具调用和文件系统能力。
|
||||
|
||||
## 设计理念
|
||||
|
||||
项目的设计目标是为开发者提供一个易于上手、功能强大的 AI 应用开发框架。我们坚持以下原则：
|
||||
|
||||
- **技术栈简洁**：选择主流且成熟的技术，降低学习和维护成本
|
||||
- **MIT 开源协议**：完全开源，允许自由使用和二次开发
|
||||
- **容器化部署**：通过 Docker Compose 管理，简化部署流程
|
||||
|
||||
## 技术架构
|
||||
|
||||
| 层级 | 技术 | 用途 |
|
||||
|------|------|------|
|
||||
| 前端 | Vue.js 3, Vite, Ant Design Vue | 现代响应式 UI 框架与组件库 |
|
||||
| 状态管理 | Pinia | 前端集中式状态管理 |
|
||||
| 后端 API | FastAPI, Uvicorn | 高性能异步 Python Web 框架 |
|
||||
| Agent 框架 | LangGraph | Agent 编排、状态管理与 checkpoint |
|
||||
| 知识库 | Milvus（可建库入库）、Dify / Notion（只读连接器） | 向量知识库 RAG 与外部只读数据源检索 |
|
||||
| 图数据库 | Neo4j | Milvus 知识库内知识图谱存储与查询 |
|
||||
| 文档处理 | MinerU, PaddleX, RapidOCR | 多格式文档解析与 OCR |
|
||||
| 任务队列 | Redis, PostgreSQL Workers | 异步任务处理 |
|
||||
| 对象存储 | MinIO | 文件与文档存储 |
|
||||
| 关系型数据库 | PostgreSQL | 元数据与用户数据持久化 |
|
||||
| 部署 | Docker, Docker Compose | 容器化部署与编排 |
|
||||
|
||||
|
||||
## 核心能力
|
||||
|
||||
Yuxi 的核心能力不在于“把大模型接进来”，而在于把 **智能体开发、知识库/RAG、知识图谱** 放进同一套系统里，并让它们在运行时真正协同工作。
|
||||
|
||||
### 1. 面向真实业务的智能体开发
|
||||
|
||||
Yuxi 基于 LangGraph 提供智能体开发能力，不只是一个固定问答入口，而是一套可配置、可扩展的 Agent 运行框架。开发者可以围绕同一个 Agent 配置模型、提示词、工具、MCP、Skills、子智能体与中间件，使“对话能力”变成“可编排的业务能力”。
|
||||
|
||||
这一层是项目的控制中心，决定了模型如何调用工具、如何访问知识、如何接入文件系统以及如何与其他子智能体协作。
|
||||
|
||||
### 2. 知识库与 RAG 一体化能力
|
||||
|
||||
Yuxi 提供完整的知识入库链路，而不是只做检索接口封装。文档从上传开始，会经过解析、分块、向量化、检索配置和评估等阶段，最终成为 Agent 可直接调用的知识来源。
|
||||
|
||||
将组织的文档转换为智能对话助手。上传 PDF 手册、技术规格、政策文档和培训材料，以创建可搜索、具备推理能力的知识库，员工可以使用自然语言查询。
|
||||
该系统能够理解复杂的问题，并提供带有来源引用的上下文感知答案。
|
||||
|
||||
|
||||
### 3. 知识图谱参与推理，而不只是展示
|
||||
|
||||
Yuxi 的知识图谱能力不是孤立的可视化模块，而是和 Milvus 知识库入库链路联动的。系统可以从已入库 chunks 中抽取实体和关系，写入 Neo4j 与 PostgreSQL 并为唯一实体/三元组建立 Milvus 语义索引；检索时可召回图谱实体与三元组，并与 chunk 命中结果融合（RRF），在知识库详情页展示和检索子图。
|
||||
|
||||
### 4. 面向生产落地的文档理解与平台能力
|
||||
|
||||
为了让知识真正可用，Yuxi 集成了 MinerU、PP-Structure-V3、RapidOCR、DeepSeek OCR 等解析能力，覆盖 PDF、Office、Markdown、图片等常见格式，解决原始资料进入系统前的结构化处理问题。
|
||||
|
||||
在此基础上，平台还补齐了业务落地常用的工程能力，例如：
|
||||
|
||||
- 部门与权限管理
|
||||
- 内容审查与守卫能力
|
||||
- 文件管理与任务管理
|
||||
- Docker Compose 部署与热重载开发
|
||||
|
||||
|
||||
## 适用场景
|
||||
|
||||
Yuxi 适用于以下场景：
|
||||
|
||||
- **企业知识库**：构建私有知识问答系统
|
||||
- **智能客服**：基于文档的自动问答
|
||||
- **知识管理**：文档自动解析、分类、构建图谱
|
||||
- **AI 应用开发**：快速构建基于大模型的应用原型
|
||||
|
||||
## 下一步
|
||||
|
||||
- 快速开始：阅读 [快速开始指南](./quick-start.md)
|
||||
- 模型配置：阅读 [模型配置](./model-config.md)
|
||||
- 知识库使用：阅读 [知识库与知识图谱](./knowledge-base.md)
|
||||
- 智能体开发：阅读 [智能体开发](../agents/agents-config.md)
|
||||
@@ -0,0 +1,178 @@
|
||||
# 快速开始指南
|
||||
|
||||
欢迎使用 Yuxi（语析），这是一个智能知识库和知识图谱 Agent 开发平台。
|
||||
本指南将帮助你在几分钟内启动并运行系统，使你能够利用 LangGraph、RAG 技术和知识图谱构建 AI 驱动的知识应用。
|
||||
|
||||
|
||||
|
||||
|
||||
::: tip 提示
|
||||
除了此文档网站外，你还可以访问 [Zread](https://zread.ai/xerrors/Yuxi) 或 [DeepWiki](https://deepwiki.com/xerrors/Yuxi) 查看自动生成的详细项目文档。
|
||||
:::
|
||||
|
||||
## 环境要求
|
||||
|
||||
项目采用微服务架构设计，默认服务无需 GPU 支持。如果需要使用 OCR 功能，可以通过环境变量配置外部服务。
|
||||
|
||||
## 快速安装
|
||||
|
||||
### 步骤一：获取项目代码
|
||||
|
||||
```bash
|
||||
# 克隆最新版本
|
||||
git clone --branch v0.7.1.beta1 --depth 1 https://github.com/xerrors/Yuxi.git
|
||||
cd Yuxi
|
||||
```
|
||||
|
||||
`--depth 1` 标志会创建一个浅克隆，仅包含最新的提交，从而显著减少下载时间和磁盘使用量。下表提供了版本选择的指导。
|
||||
|
||||
| 版本 | 适用场景 |
|
||||
|------|----------|
|
||||
| v0.7.0 | 当前稳定版本，推荐生产使用 |
|
||||
| main | 开发版本，包含最新特性（可能不稳定） |
|
||||
|
||||
### 步骤二：配置环境变量
|
||||
|
||||
**方式一：使用初始化脚本（推荐）**
|
||||
|
||||
我们提供了自动化脚本，帮你完成环境配置和 Docker 镜像拉取：
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
./scripts/init.sh
|
||||
|
||||
# Windows PowerShell
|
||||
.\scripts\init.ps1
|
||||
```
|
||||
|
||||
脚本会引导你完成以下配置：
|
||||
- 创建 `.env` 配置文件
|
||||
- 设置 `SILICONFLOW_API_KEY`（必需，用于调用大模型）
|
||||
- 设置 `TAVILY_API_KEY`（可选，用于搜索服务）
|
||||
- 自动拉取必需的 Docker 镜像
|
||||
|
||||
::: tip API Key 获取
|
||||
- **硅基流动**：访问 [cloud.siliconflow.cn](https://cloud.siliconflow.cn/i/Eo5yTHGJ)，注册认证即送 16 元额度
|
||||
- **Tavily**：访问 [app.tavily.com](https://app.tavily.com/) 获取搜索 API Key（可选）
|
||||
:::
|
||||
|
||||
**方式二：手动配置**
|
||||
|
||||
如果偏好手动配置：
|
||||
|
||||
```bash
|
||||
# 复制环境变量模板
|
||||
cp .env.template .env
|
||||
|
||||
# 编辑 .env 文件，填入你的 API Key
|
||||
```
|
||||
|
||||
### 步骤三：启动服务
|
||||
|
||||
```bash
|
||||
# 构建并启动所有服务
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
服务首次启动需要等待镜像拉取和编译，请耐心等待 2-3 分钟。
|
||||
|
||||
::: tip 轻量模式（Lite Mode）
|
||||
如果你不需要知识库和知识图谱功能，可以使用轻量模式启动，跳过 Milvus、Neo4j、etcd 等服务，节省系统资源：
|
||||
|
||||
```bash
|
||||
make up-lite # macOS or Linux
|
||||
```
|
||||
|
||||
轻量模式仅启动核心服务（前端、后端、PostgreSQL、Redis、MinIO），前端侧边栏会自动隐藏知识库和图谱入口。切换回完整模式只需运行 `make up`。
|
||||
:::
|
||||
|
||||
### 步骤四：访问系统
|
||||
|
||||
服务启动后，访问以下地址：
|
||||
|
||||
| 服务 | 地址 |
|
||||
|------|------|
|
||||
| Web 界面 | http://localhost:5173 |
|
||||
| API 文档 | http://localhost:5050/docs |
|
||||
|
||||
首次访问时，系统会要求你设置超级管理员账号和密码，请妥善保存。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 查看服务状态
|
||||
|
||||
```bash
|
||||
# 查看所有容器状态
|
||||
docker ps
|
||||
|
||||
# 实时查看后端日志
|
||||
docker logs api-dev -f
|
||||
|
||||
# 实时查看前端日志
|
||||
docker logs web-dev -f
|
||||
```
|
||||
|
||||
### 常见问题
|
||||
|
||||
<details>
|
||||
<summary><strong>Docker 镜像拉取失败</strong></summary>
|
||||
|
||||
如果网络原因导致镜像拉取失败，可以尝试：
|
||||
|
||||
```bash
|
||||
# 手动拉取基础镜像
|
||||
bash scripts/pull_image.sh python:3.13-slim
|
||||
```
|
||||
|
||||
**离线环境部署方案**：
|
||||
|
||||
```bash
|
||||
# 在有网络的环境导出镜像，注意检查镜像列表，不一定是最新的。
|
||||
bash docker/save_docker_images.sh
|
||||
|
||||
# 传输到目标机器
|
||||
scp docker_images_xxx.tar user@host:/path/
|
||||
|
||||
# 导入镜像
|
||||
docker load -i docker_images_xxx.tar
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>构建失败</strong></summary>
|
||||
|
||||
多数构建失败是由于网络问题。尝试配置代理：
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
export HTTP_PROXY=http://IP:PORT
|
||||
export HTTPS_PROXY=http://IP:PORT
|
||||
|
||||
# Windows PowerShell
|
||||
$env:HTTP_PROXY="http://IP:PORT"
|
||||
$env:HTTPS_PROXY="http://IP:PORT"
|
||||
```
|
||||
|
||||
如果配置代理后反而失败，尝试移除代理后重试。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Milvus 服务启动失败</strong></summary>
|
||||
|
||||
```bash
|
||||
# 重启 Milvus 服务
|
||||
docker compose up milvus -d
|
||||
docker restart api-dev
|
||||
```
|
||||
</details>
|
||||
|
||||
::: tip 调试面板
|
||||
前端提供了调试面板（在头像菜单中可找到），可以查看详细的请求和响应信息。生产环境建议关闭此特性。
|
||||
:::
|
||||
|
||||
## 下一步
|
||||
|
||||
- 了解如何配置模型：阅读 [模型配置](./model-config.md)
|
||||
- 探索知识库功能：阅读 [知识库与知识图谱](./knowledge-base.md)
|
||||
- 学习智能体开发：阅读 [智能体开发](../agents/agents-config.md)
|
||||
- 深入了解配置系统：阅读 [配置系统详解](../advanced/configuration.md)
|
||||
Reference in New Issue
Block a user