快速上手
Yudo 是一个面向水利工程的 AI 知识库助手，核心能力是语义检索与学术问答（图片型 PDF 由 OCR 识别后同样可检索）。拥有 4 项工具技能，由 LLM 自主判断何时调用。
核心架构
Yudo 采用 LLM + Host 双层 Agent 架构：LLM ↔ Host（app.py，进程内执行全部工具）
与普通 RAG 不同，Yudo 没有硬编码分支——所有行为由 LLM 自主决策。当 LLM 返回 tool_calls 时，Host 在进程内执行对应工具（host_tools.py），结果以 tool role 发回 LLM 进行第二轮生成。
知识库工具（search_agent.py / host_tools.py）：检索、读取、浏览知识库，其中检索走 LLM 子 Agent 管线并访问向量库。
记忆工具：直接操作用户状态，无需额外进程。
RAG 索引与检索
3.1 索引阶段（上传/重建索引时）
上传文件后，系统根据文件类型选择对应解析器，生成文本嵌入向量。图片型 PDF（无文本层）由讯飞 OCRforLLM 识别为可读文本（含 LaTeX 公式）后一并向量化：
3.2 检索阶段（用户提问时）
由于数据库较小，暂未建立 IVF 等粗筛层，向量检索采用精确扫描。
3.3 向量空间可视化
点击侧边栏的 【向量】 按钮打开 3D 可视化页面，可直观查看向量空间分布：
- 文本块：按文件着色，使用标准色板（蓝、绿、橙、紫等 10 色循环）
- 统计栏：显示
X 个片段 · N 个文件 - 文件面板：每文件显示片段总数
PCA 降维将 2048 维向量投影到 3D 空间。同主题的文本块会在空间中聚集，便于理解检索相似性。
工具清单
知识库工具（host_tools.py，进程内执行）
| 工具名 | 功能 | 参数 |
|---|---|---|
search_knowledge_base |
语义检索知识库，自动经过子 Agent 优化流程（AI 空间判断 → 关键词优化 → HyDE → 混合检索 → 摘要提取）。支持文献/代码双空间，AI 自动判断检索范围 | query：搜索语句 |
read_knowledge_file |
根据文件名读取知识库中的文件全文（截断至 1 万字符） | filename：含扩展名的文件名 |
list_knowledge_folder |
浏览知识库目录结构（最多 3 层），含文件大小 | path（可选）：子路径 |
记忆工具（host_tools.py）
| 工具名 | 功能 | 参数 |
|---|---|---|
write_note |
将文本写入 Yudo 的记忆笔记（user_preferences.md） |
text：自由文本 |
4.3 子 Agent 搜索流程
search_knowledge_base 始终经过子 Agent 处理：
- AI 空间判断：LLM 分析问题属于"文献空间"(document)还是"代码空间"(code)，决定检索范围
- 关键词优化：LLM 分析原始问题，改写为更适合向量检索的语句
- HyDE 假想文档（可选）：LLM 生成一段可能的答案段落，用于增强向量匹配
- 混合检索：向量检索 + BM25 关键词检索，分数融合。仅在指定空间中搜索
- 跨空间 fallback：若当前空间无结果，自动尝试另一空间
- 摘要提取：逐篇提取摘要/引言/结论/匹配片段
- 结构化输出：返回带相关度评分的文献摘要给主 Agent
PDF、Word、TXT 等学术资料归入 文献空间（document）；Python、JavaScript、C++ 等编程代码归入 代码空间（code）。检索时 AI 自动判断问题类型，只搜索相关空间，提升检索精度。
界面说明
5.1 主界面布局
5.2 工具调用气泡
Yudo 调用工具时，气泡内实时显示当前活动（带旋转动画），如：
- 正在搜索知识库 · 关键词
- 正在读取文件 · xxx.pdf
- 正在浏览目录
LLM 开始输出文本后，状态标记为"完成"。最终回复下方保留可折叠的调用历史。
5.3 设置面板
| 设置项 | 说明 | 默认值 |
|---|---|---|
| 主题配色 | 5 种主题切换（学术蓝/深海藏蓝/青屿松石/晴空浅蓝/竹影青雾） | 默认 (学术蓝) |
| LLM 模型 | DeepSeek 模型名称（支持运行时修改，检索子 Agent 实时同步） | deepseek-v4-flash |
| 携带上下文条数 | 每轮携带的历史消息数 | 20 |
| 检索上限 (TOP_K) | 每次检索返回的片段数 | 5 |
| 相似度阈值 | 低于此分数的片段被过滤（滑块调整，主题色填充） | 0.30 |
点击"保存"按钮后，配置持久化到 search_config.json。检索子 Agent 每次调用时读取该文件，自动同步模型名变更。
对话导出
聊天头部新增 按钮，点击可将当前会话的全部对话记录导出为 Markdown 文件，便于保存和分享问答结果。
向量空间可视化
在聊天头部点击 坐标轴图标 打开向量可视化页面：
- 左右双 3D 场景：左侧显示文献空间点云，右侧显示代码空间点云，各自独立 PCA 降维
- 双侧文件面板：左侧文献列表、右侧代码列表，可分别隐藏/展开
- 颜色标识：每个文件分配独立颜色，图片块叠加暖橙色区分
阅读器支持
- 语法高亮：代码文件（.py/.js/.ts/.java/.cpp/.css 等）使用 highlight.js 自动着色
- 主题联动：阅读器自动继承主页的主题配色设置（深海藏蓝/青屿松石等）
- 公式渲染：KaTeX 渲染 LaTeX 数学公式
- PDF 阅读：内嵌 PDF.js 渲染器，支持缩放/翻页
记忆与角色系统
所有配置统一存放在 role_and_memory/ 文件夹：
| 文件 | 内容 | 管理者 |
|---|---|---|
yudo_persona.md | AI Agent 人设、技能、行为准则 | 可手动编辑 |
context.json | 对话历史（最近 200 条） | 系统自动管理 |
user_preferences.md | 记忆笔记（带时间戳的自由文本） | Yudo 通过 write_note 写入 |
6.1 System Prompt 构成
编辑 role_and_memory/yudo_persona.md，重启后生效。
文件管理
7.1 支持格式
| 类别 | 格式 |
|---|---|
| 文档 | PDF DOCX DOC |
| 文本 | TXT MD |
| Python代码 | PY |
| JavaScript代码 | JS |
| TypeScript代码 | TS |
| Java代码 | JAVA |
| C/C++代码 | CPP C H |
| HTML文件 | HTML HTM |
| CSS文件 | CSS |
| 数据 | JSON XML CSV XLSX |
| 演示 | PPT PPTX |
7.2 分块策略
不同类型文件采用不同的分块策略：
- 文献文件（PDF/DOCX/TXT/MD）：语义分块，按章节标题和段落边界切分，200-1200 字符/块，带句子重叠
- 代码文件（PY/JS/TS/JAVA/CPP/C/CSS/HTML）：结构分块，按函数/类/方法边界切分，优先保持函数完整性
7.3 重建索引
上传新文件后，系统自动建立索引。如需重建全部索引，在设置面板点击"重建索引"：
50 篇 PDF 重新解析并生成向量可能需要数分钟。重建过程在后台异步执行，不影响其他操作。
配置说明
8.1 核心配置（config.py）
| 配置项 | 说明 | 默认值 |
|---|---|---|
DEEPSEEK_API_KEY | DeepSeek API 密钥 | 硬编码（生产环境用环境变量覆盖） |
DEEPSEEK_MODEL | 默认 LLM 模型名 | deepseek-v4-flash |
ARK_API_KEY | 火山引擎 Ark API 密钥 | 硬编码 |
ARK_EMBEDDING_MODEL | 文本嵌入模型 | doubao-embedding-vision-251215 |
ARK_EMBEDDING_DIM | 嵌入向量维度 | 2048 |
ENABLE_HYDE | 是否启用 HyDE 假想文档 | True |
BM25_K1 / BM25_B | BM25 关键词检索参数 | 1.5 / 0.75 |
8.2 运行时配置（search_config.json）
通过设置面板修改，持久化到 search_config.json：
| 字段 | 说明 | 默认值 |
|---|---|---|
model | 运行时 LLM 模型名（检索子 Agent 自动同步） | deepseek-v4-flash |
top_k | 检索返回片段数 | 5 |
similarity_threshold | 相似度阈值 | 0.3 |
context_count | 携带上下文条数 | 20 |
8.3 权限说明
| 操作 | 权限要求 |
|---|---|
| 对话 / 搜索 / 上传文件 | 登录用户 |
| 修改设置 / 重建索引 | 登录用户 |
| 开发者统计 | 白名单账号 |
常见问题
Yudo 是 Agent，不是 pipeline。普通 RAG 是固定流程：搜索→拼接→回答。Yudo 自主判断要不要搜索、用什么词搜索、搜完是否需要读全文、是否需要记录信息。没有硬编码分支。
能。没有文本层的页面在上传解析时会自动拼接成一张长图，调用讯飞 OCRforLLM 识别正文与公式（LaTeX），识别结果作为可读文本进入向量索引与模型读取。前端阅读器仍展示原始 PDF。
每次调用 search_knowledge_base 都走子 Agent 流程。子 Agent 优化关键词 → HyDE 生成假想文档 → 混合检索 → 提取摘要 → 返回结构化结果，即使只匹配到 1 篇也走完整流程以保证质量。
设置面板保存模型名后，写入 search_config.json。检索子 Agent 每次调用时读取该文件，关键词优化和 HyDE 调用会自动使用新模型名。
不会。Yudo 基于 DeepSeek 内置知识 + 本地知识库文件回答。
运行 backup.sh 脚本自动备份知识库文件、向量索引、配置和记忆数据到 backup 目录。
上传文件时，系统根据扩展名自动归类：PDF/DOCX/TXT/MD 等归入文献空间，PY/JS/TS/JAVA 等代码文件归入代码空间。检索时 AI 判断问题类型，只搜索相关空间，避免文献结果干扰代码查找。如果一个空间无结果，系统会自动尝试另一个空间。
不一样。文献文件按章节和段落边界做语义分块（200-1200 字符）。代码文件则按函数、类、方法边界做结构分块，每个函数/类独立成块，保证代码逻辑完整性。支持 Python、JavaScript、TypeScript、Java、C/C++、HTML、CSS 七种语言。