Yuxi-Know：智能知识库与知识图谱问答平台完全指南

一、核心价值：重新定义知识管理的AI助手

Yuxi-Know是一款融合大模型RAG技术（基于检索的生成式问答）与知识图谱的智能问答平台。通过Llamaindex、VueJS、FastAPI和Neo4j的技术组合，实现了三大核心突破：

🔍 双引擎知识系统：结合向量数据库的文档检索与图数据库的关系推理，让AI回答既有细节又有逻辑深度
📁 全格式内容处理：支持PDF、TXT、MD等10+文档格式的智能解析，自动提取关键信息
⚙️ 多模型灵活适配：兼容OpenAI、国内主流API服务及本地部署模型（vllm/ollama），满足不同场景需求

图1：Yuxi-Know智能体交互界面，支持文件上传、工具调用与多轮对话

二、快速上手：三步启动你的智能知识库

2.1 环境准备（5分钟完成）

📌 核心提示：项目需要API密钥才能运行，建议提前注册至少一个模型服务账号

1. 获取代码

git clone https://gitcode.com/GitHub_Trending/yu/Yuxi-Know
cd Yuxi-Know

2. 配置环境变量
   创建src/.env文件（参考项目中的src/config/static/info.template.yaml），添加必要配置：

# 至少配置一个模型API密钥
OPENAI_API_KEY=your_key_here
# 或国内模型
ZHIPUAI_API_KEY=your_key_here

3. 启动服务
   根据使用场景选择对应命令：

环境类型	命令	特点
开发环境	docker compose -f docker-compose.yml --env-file src/.env up --build	实时热重载，适合调试
生产环境	docker compose -f docker-compose.prod.yml --env-file src/.env up --build -d	后台运行，性能优化

⚠️ 注意事项：首次启动会自动拉取镜像，国内用户建议配置Docker镜像加速

2.2 基础操作指南

成功启动后访问http://localhost:5173/进入系统，完成三个关键步骤：

1. 创建知识库
   在左侧导航栏选择"知识库"→"新建"，填写名称并选择存储类型（向量库/混合库）

2. 上传文档
   点击"上传文件"按钮，支持批量导入：

   • 文本类：TXT/MD/DOCX（自动分段处理）
   • 格式类：PDF/PPT（保留排版结构）
   • 表格类：XLSX/CSV（自动识别表头）

3. 开始对话
   在聊天界面输入问题，系统会自动检索相关知识并生成回答。可通过右上角"设置"调整回答长度和相关性阈值

三、深度应用：知识图谱与高级配置

3.1 知识图谱构建指南

知识图谱是Yuxi-Know的核心特色，通过实体关系网络实现深度问答：

图2：Neo4j浏览器展示的实体关系网络，节点大小代表关联强度

1. 数据准备
   按JSONL格式准备图谱数据，每行一条关系记录：

   {"h": "实体1", "t": "实体2", "r": "关系类型"}
   {"h": "人工智能", "t": "机器学习", "r": "包含"}
   

2. 导入流程

   • 进入"图谱管理"→"导入"
   • 上传JSONL文件并选择实体类型映射
   • 等待系统完成图谱构建（大型文件建议分批导入）

3. 查询技巧
   使用特定关键词触发图谱查询：

   • "显示XX的相关实体"
   • "XX和YY之间有什么关系"
   • "列举所有属于XX类别的实体"

3.2 模型配置与优化

系统支持多模型协同工作，通过配置文件实现精细化管理：

🔧 模型配置文件：src/config/static/models.py

图3：在models.yaml中添加新模型的示例，需与官方API名称保持一致

配置要点：

• base_url：API服务地址（本地模型填写vllm/ollama地址）
• default：默认使用的模型
• env：环境变量名称（需与.env文件对应）
• models：支持的模型列表（需与官方名称一致）

性能优化建议：

• 长文档处理：选择支持长上下文的模型（如glm-4-long）
• 本地部署：使用vllm部署7B模型，配置max_num_batched_tokens参数提升吞吐量
• 成本控制：设置模型优先级，简单问题使用轻量级模型

四、生态拓展：集成与定制开发

4.1 典型生态集成方案

Yuxi-Know设计了开放的集成接口，支持与多种工具链协作：

📊 向量数据库集成

• 内置支持Milvus/Chroma等向量库
• 配置路径：src/knowledge/implementations/milvus.py
• 版本兼容性：Milvus 2.2.x+，Chroma 0.4.x+

🔌 OCR与文档处理
系统内置多种文档解析器：

• plugins/mineru_parser.py：处理复杂格式文档
• plugins/rapid_ocr_processor.py：图片文字识别
• plugins/paddlex_parser.py：表格结构提取

4.2 自定义智能体开发

高级用户可通过以下步骤扩展系统能力：

1. 创建智能体模板
   在src/agents/目录下创建新智能体目录，包含：

   • graph.py：定义工作流逻辑
   • metadata.toml：配置智能体基本信息
   • tools.py：注册自定义工具

2. 注册工具函数
   通过@tool装饰器定义工具：

   from src.agents.common.tools import tool
   
   @tool
   def weather_query(city: str) -> str:
       """查询指定城市天气"""
       return get_weather_data(city)
   

3. 测试与部署
   使用test/test_agent_configs.py验证智能体配置，通过Web界面加载使用

五、常见问题排查

5.1 启动问题

错误现象	可能原因	解决方案
容器启动后立即退出	环境变量配置错误	检查.env文件，确保必填项完整
Neo4j连接失败	端口冲突	修改docker-compose中的neo4j端口映射
前端白屏	依赖未安装	进入web目录执行npm install

5.2 功能异常

• 文档上传失败：检查文件大小（建议单文件<100MB），尝试分割大型文档
• 回答质量低：在设置中提高"相关性阈值"，或切换更强大的模型
• 图谱查询无结果：确认实体名称与图谱数据一致，尝试同义词查询

5.3 性能优化

• 数据库优化：定期执行scripts/rename_milvus_collections.py整理向量库
• 缓存策略：启用Redis缓存（修改src/config/app.py中的CACHE配置）
• 资源调整：根据硬件配置修改docker-compose中的内存限制

通过本指南，您已掌握Yuxi-Know的核心功能与高级应用技巧。无论是构建企业知识库，还是开发定制化智能助手，这款开源工具都能提供强大支持。访问项目中的docs/目录可获取更多技术细节与API文档。