创建第一个智能体

本页带你用最少代码,跑通一个具备工具调用能力的智能体。

1. 目标

构建一个可以咨询人事制度的RAG智能体

2. 登录项目

打开浏览器访问 http://localhost:8189 alt text

默认的账号是：admin 密码是: 123456

3. 配置大模型

点击左下角登录的用户，弹出的菜单点击模型设置 alt text 进入到模型配置页面，我们可以看到各种需要的模型配置

系统把大模型按职责分成了四类,各司其职。先理解它们分别"干嘛的",配置才不会迷茫:

3.1 对话模型(Chat Model)

整个系统的"大脑",负责理解问题和生成最终回答。

用户提问、意图理解、阅读检索结果、组织语言输出 —— 全由它完成
也是调用 MCP 工具、做推理决策的主体
选型要点:指令遵循能力和中文生成质量最重要
推荐场景:日常问答、客服、助手类应用
典型选择:gpt-4o-mini、deepseek-chat、qwen-plus、本地 qwen2.5:7b 等

💡 可以理解为:它是和你直接"对话"的那位 AI。

3.2 向量模型(Embedding Model)

负责把文字变成数字向量,是"能否检索得到"的关键。

知识库入库时,它把每段文档转成一个向量存进数据库
用户提问时,它再把问题转成向量,用于在库里"算相似度"找最相关的内容
它不生成文字,只做文本 → 向量的转换
选型要点:与中文语义匹配度强相关,直接决定 RAG 召回质量
典型选择:text-embedding-3-small、bge-large-zh、m3e-base 等

💡 对话模型决定"答得好不好",向量模型决定"找得准不准"——两个都很关键。

3.3 重排模型(Rerank Model)

给初步检索出来的结果"二次打分、重新排序",让最相关的排到最前。

向量检索会一次召回一批候选(比如 TopK=20),里面难免混入"看起来像但其实不相关"的内容
重排模型逐条精细评估 query 与每条候选的相关度,重新排序后只保留最精华的几条喂给对话模型
它只排序、不改变内容,但能显著提升最终回答质量、降低幻觉
选型要点:看 rerank 准确率指标,与所用向量模型不必同源
典型选择:bge-reranker-v2-m3、rerank-multilingual-v2.0 等

💡 可以理解为:向量模型是"海选",重排模型是"终面"。

3.4 视觉模型(Vision Model)

能"看懂"图片,用于解析知识库里的图表、扫描件、截图等图像内容。

文档入库时,遇到图片/PDF 扫描页,视觉模型识别图中文字与含义,转成可检索的文本
也支持用户直接发图提问(多模态对话)
不配置的话,含图文档里的图像信息将无法被检索和使用
选型要点:看 OCR 准确率 + 中文图表理解能力
典型选择:gpt-4o、qwen-vl-max、glm-4v 等

💡 如果你的知识库纯文字、没有图片,这一项可以不配。

3.5 四类模型协作关系

一次完整的 RAG 问答,四类模型是这样配合的:

用户提问
   │
   ▼
[对话模型] 理解问题 / 改写查询
   │
   ▼
[向量模型] 把问题转成向量 → 在知识库中检索 TopK 候选
   │
   ▼
[重排模型] 对候选结果精排,保留最相关的几条
   │
   ▼
[对话模型] 结合检索证据,生成最终回答

(若知识库含图) → [视觉模型] 在入库阶段已把图像转成文字

3.6 配置建议速查

你的场景	对话模型	向量模型	重排模型	视觉模型
纯文字问答(基础)	✅ 必配	✅ 必配	⚪ 可选	❌ 不配
高质量 RAG(推荐)	✅	✅	✅ 建议配	❌
含图文档/扫描件	✅	✅	✅	✅ 必配
多模态对话(发图提问)	✅(需支持视觉)	✅	✅	✅

3.7 以对话模型为例子

点击右上角的新增模型 alt text

弹出新增模型的表单,各字段含义如下:

模型名字

给这个模型起一个好记的标签,纯粹为了方便区分和选择。

它不是发给模型厂商的真实模型名(那是「可用模型」字段),而是你在系统里看到的名字
比如同一个 gpt-4o-mini,你可以叫它「线上-便宜版」「测试用」「客服专用」,一眼就知道用途
在创建智能体、选模型时,下拉框里显示的就是这个名字
建议:用途 + 型号 的命名方式,如「客服主模型-deepseek」

API 秘钥

调用模型厂商接口的"通行证",系统拿它去验证你有没有权限用这个模型。

从模型服务商后台申请(OpenAI / DeepSeek / 智谱 / 阿里云百炼等都有各自的 Key)
一个 Key 对应一个账号,按调用量计费,请妥善保管、不要泄露
不同厂商的 Key 不能混用(DeepSeek 的 Key 只能配 DeepSeek 的接口)

可用模型(多个用逗号隔开)

填模型厂商提供的真实模型 ID,告诉系统"这个 Key 能调用哪些模型"。

这里写的是厂商定义的模型名,必须和官方文档完全一致(如 gpt-4o-mini、deepseek-chat、qwen-plus)
支持多个,用英文逗号 , 隔开,系统会按顺序作为候选:
- 第一个模型不可用(熔断/限流)时,自动切换到下一个
- 这就是 SparkX「多模型路由 + 自动降级」能力的基础
示例:deepseek-chat, qwen-plus, gpt-4o-mini

💡 配多个模型 = 给你的应用上"保险",挂一个还有备胎顶上。

接口地址

模型厂商的对话接口完整 URL,系统往这里发请求。必须填到具体端点,不能只填到 /v1。

✅ 要填完整端点地址,例如:
- DeepSeek:https://api.deepseek.com/v1/chat/completions
- OpenAI:https://api.openai.com/v1/chat/completions
- 通义千问:https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
❌ 不能只填到 /v1(虽然 OpenAI 官方约定如此,但很多厂商并不遵守):
- https://api.deepseek.com/v1 ← 不完整,可能调不通
- https://api.openai.com ← 缺路径,必失败
⚠️ 不同厂商的端点路径差异很大,大模型厂家不一定都遵守 OpenAI 的 /v1/chat/completions 约定,有的会是 /api/chat、/v2/messages 等自定义路径
👉 正确做法:去对应厂商的 API 文档里,找到"对话接口 / Chat Completions"那一条,直接复制文档示例里的完整请求地址
地址必须和 API Key 是同一来源,张冠李戴会报 401

💡 填对没有?点击下方「测试」按钮试一下,地址不对通常会直接报 404 或连接失败。

温度(Temperature)

控制回答的"随机性 / 创造性",取值范围一般是 0 ~ 2。

温度低(0 ~ 0.3):回答稳定、严谨、可复现 —— 适合知识问答、客服、RAG(推荐)
温度高(0.7 ~ 1.2):回答发散、有创意 —— 适合写文案、头脑风暴、闲聊
RAG 场景建议 0.1 ~ 0.3,让模型老老实实基于检索内容回答,减少"自由发挥"导致的幻觉

最大输出(Max Tokens)

限制模型单次回答的最大字数(token 数),防止回答过长导致超时或费用失控。

1 个 token ≈ 1.5 个汉字,2048 tokens 约等于 3000 字
设太小:回答会被中途截断;设太大:可能浪费成本、拖慢响应
知识问答一般 1024 ~ 2048 够用;长文生成可调到 4096+

测试

保存前先验证配置是否正确,避免配错了才发现。

点击后会用你填的「接口地址 + API Key + 可用模型」真实发起一次调用
返回成功 → 说明三项配置都对,可以放心保存
返回报错 → 根据提示排查(401=Key 错;404=地址错;模型名不对等)
强烈建议每次新增/修改模型都先点一下测试,省得后面智能体报错再回头查

4. 创建知识库

点击 知识库 菜单，进入知识库管理页面 alt text 点击右上角的新建知识库，能看到我们需要填写的内容

表单里两个字段的作用如下:

4.1 知识库名称

给这个知识库起一个名字,方便区分和管理。

纯标签用途,不影响检索效果,你可以按业务/部门/文档类型来命名
一个系统里可以建多个知识库,各自独立(例如:人事制度库、财务报销库、产品手册库)
建议命名清晰可辨,后续给智能体绑定知识库时,下拉框里一眼就能选对

💡 一个智能体可以同时绑定多个知识库,所以按主题拆分比"全塞进一个库"更好维护。

4.2 向量模型

决定这个知识库用哪种向量模型来"理解文字",是检索准不准的核心配置。

它的作用在配置大模型 - 向量模型已详细介绍,这里只说为什么要在创建知识库时选:
⚠️ 关键点:向量模型一经选定,知识库内所有文档都会用它来生成向量并存储。
- 入库时:每段文档用「这个向量模型」转成向量存进库
- 检索时:用户提问也必须用同一个向量模型转成向量,才能正确算相似度
- 不同向量模型产出的向量维度和空间都不一样,彼此无法比较
因此:
- ❌ 创建知识库后不能随意更换向量模型,换了等于已有文档全部作废,需要重新入库
- ✅ 如果确实要换,请新建一个知识库 + 重新上传文档
选型建议:与对话模型不必同源,优先选中文语义匹配度好的(如 bge-large-zh、m3e-base)

💡 简单记:知识库的"向量模型"一旦定下来,基本就绑死了,创建前先想好用哪个。

⚠️ 注意事项:向量模型创建后不可更改

这是新建知识库时最容易踩坑的一点,务必先看懂再动手。

为什么不能改?

向量模型的作用是把文字"翻译"成一串数字(向量),而不同向量模型翻译出的数字体系完全不同:

维度不同:bge-large-zh 是 1024 维,m3e-base 是 768 维
空间不同:即使是同样的维度,每个数字代表的语义也完全不一样
结果:A 模型生成的向量,B 模型根本无法理解和比较,就像把中文和英文混在一起算相似度

知识库里所有文档入库时已经用「创建时选定的向量模型」生成了向量,这些向量只在那一个模型的空间里有意义。

强行改了会怎样?

场景	后果
只改向量模型配置,不重新入库	🔴 检索彻底失效 —— 旧向量和新模型对不上,问什么都检索不到相关内容,或检索出一堆完全无关的垃圾结果
改完后重新提问	🔴 相似度计算全部错乱 —— query 用新模型转向量,文档是旧模型的向量,两个不在一个空间,算出来的相似度没有任何意义
整个系统层面	🔴 知识库等于废了 —— 表面还在,实际检索不出东西,智能体回答质量断崖式下跌,且不易察觉(不报错,只是"答非所问")

⚠️ 最隐蔽的危险:改了不会立刻报错,系统照常运行,但检索质量悄悄崩塌,往往要等用户反馈"怎么答非所问了"才会发现。

正确做法

如果确实需要换向量模型,请按以下步骤:

新建一个知识库,创建时选好新的向量模型
把原文档重新上传到新知识库(用新模型重新生成向量)
把智能体绑定的知识库切换到新的
验证检索正常后,再删除旧知识库

💡 一句话:向量模型 = 知识库的"基因",选定即绑定,要换就重建。 所以创建知识库前,务必先确定好用哪个向量模型。

4.3 上传文档

点击设置进入知识库管理页面 alt text 点击文档管理下的上传文档

SparkX 支持上传多种格式的文档,系统会根据文件类型自动选择合适的解析策略,把内容"读出来"再切块入库。

4.3.1 各类文档的解析策略

纯文本类(README / 日志 / 代码 / 配置等)

适用格式:.txt、.md、.log、.csv、.json、.xml、源代码等

解析方式:直接读取原文,无需复杂转换
处理重点:按段落 / 标题 / 代码块做结构化分块,保留缩进和代码格式
特点:解析最快、最准,几乎无损

Office 文档(Word / Excel / PowerPoint)

适用格式:.doc / .docx、.xls / .xlsx、.ppt / .pptx

解析方式:基于 Apache POI 提取文字、表格、幻灯片内容
Word:按段落 + 标题层级分块
Excel:按行切分(一行或一组相关行作为一个 chunk),保留列名上下文,适合"表格型问答"
PPT:按每页幻灯片为单位提取
特点:能保留文档原有结构,表格内容不会糊成一团

标准 PDF(可复制文字的电子版)

适用格式:.pdf(文字版,非扫描件)

解析方式:基于 Apache PDFBox 直接抽取文本层
处理重点:按版面识别段落、标题、列表、表格,做结构化分块(参考 ingest/block/)
特点:解析快、准确,适合大多数电子版 PDF(如制度手册、产品白皮书)

扫描件 PDF / 图片型文档(需要 OCR)

适用格式:扫描版 PDF、纯图片拼成的 PDF、.jpg / .png 图片

这类文档没有文字层,直接用 PDFBox 抽不出任何文字
解析方式:走 OCR + 视觉模型,把图像里的文字"识别"出来
处理重点:识别后同样进入结构化分块流程
特点:依赖视觉模型能力,识别准确率决定检索质量

⚠️ 如果你的文档大量是扫描件,务必配置好视觉模型,否则内容根本进不了库。

复杂版面 PDF(多栏 / 公式 / 图文混排) —— MinerU 登场

这就是 MinerU 发挥作用的场景,详见下文 4.4 MinerU 详解。

4.3.2 解析策略总览

一图理清不同文档走哪条解析路径:

              ┌─ 纯文本类 ──────────────► 直接读取 → 结构化分块
              │
              ├─ Office(doc/xls/ppt) ──► Apache POI 提取 → 分块(Excel 按行)
上传文档 ─────┤
              ├─ 标准 PDF(电子版) ────► PDFBox 抽文字 → 版面分块
              │
              ├─ 扫描件 PDF / 图片 ────► OCR + 视觉模型 → 分块
              │
              └─ 复杂版面 PDF ─────────► MinerU 解析(公式/多栏/表格) → 分块

无论走哪条路径,最终都会:

把内容切成语义完整的分块(chunk)
用知识库绑定的向量模型转成向量
存入数据库,等待检索

4.4 MinerU 详解

4.4.1 MinerU 是什么

MinerU 是 OpenDataLab 开源的专业文档版面解析工具,擅长处理"普通解析器搞不定"的复杂 PDF。

SparkX 在 ingest/mineru/ 模块对它做了封装(MinerUClient / MinerUDocumentParser / MinerUImageDescriber),支持自建部署或云端调用两种模式(在系统设置里配置)。

4.4.2 普通 PDF 解析器解决不了的问题

标准 PDFBox 对下面这些场景会"翻车":

问题场景	普通 PDFBox 的表现	MinerU 的表现
多栏排版(论文、报纸)	按物理顺序读取,左右栏文字交错混在一起,读不通	正确识别分栏,按阅读顺序重组
数学公式	抽出乱码或空字符	识别成 LaTeX 公式,可被检索和理解
复杂表格(合并单元格、跨页)	表格结构被打散成散乱文字	还原表格结构,行列对应清晰
图文混排(图配文)	分不清哪段文字配哪张图	识别图文对应关系,图片单独走视觉模型描述
标题层级 / 目录	层级信息丢失,全是平铺文字	识别标题级别,恢复文档大纲结构

4.4.3 MinerU 用在哪里

MinerU 只用在文档入库的"解析"环节,不参与问答:

文档上传 → [解析] → 分块 → 嵌入(向量化) → 入库
            ↑
        MinerU 在这里介入(仅对复杂 PDF)

具体触发时机:

系统判断文档属于复杂版面 PDF 时,自动调用 MinerU 解析
也可以在配置里强制指定某些文档走 MinerU(例如学术论文库)

4.4.4 MinerU 解决了哪些问题

学术 / 技术文档可用了:论文里的公式、多栏、参考文献不再解析成乱码
复杂表格不再丢失结构:财务报表、对比表能完整保留,支持精准问答
图文对应关系正确:回答时能准确引用"图 X 所示……"的上下文
文档大纲可检索:基于标题层级分块,检索更精准,而不是"从一锅粥里捞"

4.4.5 要不要启用 MinerU

你的文档类型	建议
纯文字、简单排版	❌ 没必要,标准解析足够,MinerU 反而慢
Word / Excel / PPT	❌ 不需要,Office 解析器直接处理
标准 PDF(电子版、简单排版)	❌ PDFBox 即可
学术论文、多栏报刊、含公式 PDF	✅ 强烈建议启用
含复杂表格 / 图文混排的 PDF	✅ 建议启用
扫描件 / 纯图片	⚪ 走 OCR 视觉模型即可,不一定用 MinerU

💡 MinerU 可以自建部署(免费、需 GPU)或用云端服务(付费、省事),在系统设置的「外部服务」里配置。启用后只在入库时多花点时间,不影响问答速度。

4.5 切割文档

alt text

文档解析出来后,需要切成一个个小段(称为 chunk / 分块),才能向量化、存入数据库供检索。怎么切,直接决定 RAG 检索质量,这是知识库最关键的配置之一。

4.5.1 为什么要切割

大模型有上下文长度限制,一整篇文档塞不进去;更重要的是,检索时要的是"最相关的那一小段",而不是整篇文档。切割的核心目的:

✅ 让每一段语义完整、长度适中,方便精准检索
✅ 控制喂给模型的上下文量,省 token、降成本
❌ 切太大:一段包含多个不相关主题,检索精度下降
❌ 切太小:语义被截断,上下文不足,回答"断章取义"

4.5.2 切割策略

SparkX 根据文档类型自动选择合适的切割策略:

固定长度切割(Fixed Size)

按固定的字符数 / token 数切块,块与块之间保留一定 重叠(overlap) 防止语义断裂
适合:纯文本、日志等没有明显结构的文档
示例:每块 500 字,重叠 50 字

结构化切割(Structural / 版面感知)

基于 ingest/block/ 模块,按文档天然的版面结构切分:段落、标题、列表、表格、代码块
保留每个分块的 Provenance 溯源信息(来自哪一段、哪一页)
适合:Word / PDF / Markdown 等有结构的文档
优势:不会把一个完整的表格或一个论点切散

父子分块(Parent-Child)—— 重点推荐

这是 SparkX 的核心特色之一(对应 ParentChildSplitter),专门解决"小段精准检索 + 大段完整上下文"的矛盾
详见下文 4.5.4 父子分块详解

按行切分(Spreadsheet Row)

专门针对 Excel,一行(或一组相关行)作为一个 chunk,并保留列名作为上下文
对应 SpreadsheetRowSplitter
适合:表格类问答(如"张三的工号是多少")

4.5.3 切割大小建议

切割大小的核心是平衡"检索精度"和"上下文完整性",没有绝对标准,但有以下经验值:

参数	建议值	说明
块大小(chunk size)	300 ~ 500 字(约 200~350 token)	大多数中文文档的甜点区。太小语义不全,太大检索稀释
重叠(overlap)	块大小的 10%~20%(约 50~100 字)	防止关键句被切断在两块之间

不同场景的调整方向

你的文档 / 场景	块大小建议	理由
FAQ / 短问答	200~300 字	每个问题+答案自成一块,精准命中
制度手册 / 操作文档	400~500 字	一个条款/步骤完整保留
长篇论述 / 论文	500~800 字	论点需要较长上下文才完整
表格 / 数据	按行切	不固定字数,保证行完整
代码 / 配置	按函数/代码块	不按字数,保证逻辑单元完整

三个判断信号

🔴 检索结果总不相关 → 块可能太大,一段里混了多个主题,试着调小
🔴 检索命中了但回答"断章取义" → 块可能太小或没开重叠,语义被切断,试着调大 / 加 overlap
🟢 配合重排模型 → 块可以切小一点,反正重排会精筛;没重排则块要稍大些保证信息完整

💡 经验法则:先用 400 字 + 80 字重叠起步,根据实际问答效果再微调。没有"一次到位"的参数,需要结合自己的文档反复测试。

4.5.4 父子分块详解

这是 SparkX 检索质量优于普通 RAG 的关键设计,值得单独理解。

它解决什么矛盾

普通切割只有一层,陷入两难:

切割方式	检索表现	回答表现
切得小(如 200 字)	✅ 检索精准,容易命中关键字	❌ 上下文不全,回答"只见树木不见森林"
切得大(如 1000 字)	❌ 检索稀释,一段里话题太多	✅ 上下文完整,回答有据

父子分块 = 同时拿到两边的优点。

工作原理

原文档
  │
  ▼ 按"较大粒度"切出【父块】(如 1000 字,语义完整)
父块1            父块2            父块3
  │                │                │
  ▼ 每个父块再切成多个【子块】(如 200 字,检索精准)
子1.1 子1.2 子1.3   子2.1 子2.2 ...   子3.1 ...

入库时:子块和父块都向量化存入数据库
检索时:用子块(小、精准)去匹配,算相似度
返回时:一旦某个子块命中,扩展返回它所在的整个父块(大、完整)

效果对比

对比项	普通单层切割	父子分块
检索精度	取决于块大小,顾此失彼	✅ 子块小,精准命中
上下文完整性	容易断章取义	✅ 父块大,语义完整
token 消耗	大块浪费 token	✅ 只在命中时返回父块,平衡

💡 一句话: 用子块"瞄准",用父块"举证" 。这也是为什么 SparkX 在检索后处理链里有专门的 ParentExpansionPostProcessor —— 命中子块后自动扩展到父块。

什么时候开 / 关

场景	建议
长文档 RAG(手册、论文、白皮书)	✅ 强烈建议开,效果提升明显
FAQ / 短问答库	⚪ 可不开,本身每条就短而完整
追求极致检索精度	✅ 开,子块小 = 命中准
文档本身段落都很短	⚪ 收益不大

4.5.5 切割参数速查表

配置项	作用	建议起步值
切割大小(chunk size)	每个分块的最大长度	400 字
重叠大小(overlap)	相邻块的重叠字数	80 字(约 10%~20%)
是否启用父子分块	小块检索 + 大块返回	✅ 开(长文档场景)
切割策略	按结构 / 按固定长度 / 按行	按文档类型自动选择

💡 这些参数在 SparkX 中通常按知识库或按文档类型配置,改了之后需要重新入库才生效(和换向量模型同理:历史分块是按旧参数切的)。

4.6 预览分块

alt text 预览分块是本系统的特色，方便你预览系统的切割效果，如果发现切割的不满意，可以返回上一步重新调整切割的大小，防止因为分块大小直接提交浪费时间和token。同时系统允许你做修改，可以对切割出来的分块进行微调，人为的增加或者删除分块。

4.7 向量化

进入文档管理列表，可以看到你上传的文档，上传好的文档，默认是没有进行向量化的。需要我们来手动执行向量化，点击后面的向量化按钮，等待系统执行完毕，向量化状态提示已完成即可。 alt text

5. 创建智能体

点击智能体菜单，点击创建智能体 alt text

智能体是用户最终对话的入口。创建/编辑表单采用左侧分类菜单 + 右侧表单的布局,左侧共 6 个标签页,下面按 基础 → 提示词 → 模型参数 → 样例查询 → 检索 → 兜底 的顺序逐个介绍。

💡 智能体的几乎所有参数都是查询时生效,改了立即保存生效,不需要重新入库(只有知识库的向量模型、切割参数这种入库配置才需要重入库)。

5.1 基础

智能体的身份与数据来源,是最先要填的部分。

名称(必填)

智能体的名字,展示在对话窗口和列表里。

最多 25 个字符,必填
建议按用途命名清晰可辨,如「人事小助手」「IT 运维问答」
纯展示用途,不影响检索和回答逻辑

描述(可选)

对智能体功能的简要说明,可选。

最多 255 字,用于备注这个智能体是干嘛的
方便管理多个智能体时区分用途

知识库

决定这个智能体能"看到"哪些知识库,是检索的数据来源。三种模式:

模式	说明	适用场景
指定知识库(默认)	勾选若干个库	✅ 生产推荐,精准控制数据范围
全部知识库	检索系统里所有库	测试 / 小规模部署
无知识库	不挂任何库,纯 LLM 对话	闲聊、工具型智能体

选「指定」后会出现关联知识库(可多选)和限定文档两个二级选项:
- 关联知识库:勾选要参与检索的库
- 限定文档(留空 = 检索整库):可选具体文档,做更细粒度的范围控制
选「全部」会提示「将检索系统中全部知识库」
选「无」会提示「不检索知识库,纯 LLM 对话(需自定义提示词约束回答)」

⚠️ 注意事项:

不同知识库可能用不同向量模型,系统会按各自库的向量模型分别检索后融合,不会出错
建议按主题绑定,一个智能体挂太多无关库会稀释检索精度
新增的知识库不会自动加入,需要手动编辑智能体勾选

对话模型

选这个智能体用哪个对话模型来"思考和回答"。

下拉框显示的是 3.7 配置模型时填的「模型名字」
留空则走系统默认模型
一个 ai_model 配了多个模型名(逗号隔开)时,下拉里会拆成多个子选项(如「线上模型 / gpt-4o-mini」「线上模型 / gpt-4o」),让你选到具体子模型

⚠️ 注意事项:

切换对话模型不影响已入库数据(这点和向量模型不同,随时可换)
不同智能体可以挂不同模型(客服用便宜模型、专家问答用强模型)

状态

智能体的启用/禁用开关。

正常:用户可见、可对话
禁用:暂时下线,用户看不到

5.2 提示词

控制智能体"怎么说话"的部分。 alt text

系统提示词

告诉模型"你是谁、怎么回答、遵循什么规则",是控制回答风格的最高指令。

每次对话时放在最前面发给模型,优先级最高
留空则使用知识库默认回答模板
示例:你是公司人事助手,只能基于知识库内容回答人事制度问题;查不到的明确说"暂无相关信息",禁止编造。

编写要点

✅ 明确角色定位:你是谁、服务谁、擅长什么
✅ 划定边界:能答什么、不能答什么、查不到怎么办
✅ 规定格式:回答风格(简洁/详细)、是否分点、是否带引用来源

⚠️ 注意事项:

❌ 不要写得太长:占 token、稀释模型对关键指令的注意力,几百字内为宜
❌ 不要互相矛盾的指令(如既要求"详细"又要求"简短")
💡 改动后立即生效,不需要重新入库

开场白

用户打开对话时看到的第一句话。

可选,用于引导用户、说明智能体能做什么
示例:你好!我是人事小助手,可以咨询请假、报销、考勤等问题。

5.3 模型参数

控制模型生成行为的数值参数。

温度(temperature)

控制回答的"随机性 / 创造性",范围 0 ~ 2。

默认 0.3,步进 0.05
温度低(0 ~ 0.3):回答稳定、严谨、可复现 —— 适合知识问答、RAG(推荐)
温度高(0.7~1.2):回答发散、有创意 —— 适合写文案、头脑风暴
RAG 场景保持默认 0.3 即可,让模型老实基于检索内容回答,减少幻觉

最大生成 token(maxTokens)

限制模型单次回答的最大长度,防止回答过长导致超时或费用失控。

默认 2048,范围 128 ~ 8192,步进 128
1 token ≈ 1.5 个汉字,2048 token 约等于 3000 字
知识问答一般 2048 够用;长文生成可调到 4096+

记忆轮数(historyTurns)

携带多少轮历史对话作为上下文。

默认 4,范围 0 ~ 20,步进 1
0 = 不带历史:每轮独立,无多轮记忆
值越大:多轮追问效果好,但 token 消耗增加
一般 3~6 轮够用;设太大可能导致上下文超限或偏离主题

意图/改写模型(rewriteModelKey)

alt text

专门用于"意图分类与查询改写"的小模型,不是用来回答的主模型。

留空则用对话默认模型
用户提问往往口语化、模糊、有指代(如"那个怎么弄"),直接检索效果差;改写模型负责把它改写成清晰、完整的检索 query
下拉同样会把多模型名拆成子选项

⚠️ 注意事项:

💡 省钱提速技巧:这里选一个小快模型(如 qwen-turbo),主回答仍用对话默认模型,既降本又提速
💡 不配也能用,但复杂问题(多轮追问、指代消解)的回答质量会打折

5.4 样例查询

alt text

高频/标准问题预先写好"标准答案",用户提问向量命中即直接返回,跳过检索和生成。(完整原理见样例查询)

这一页只有两个开关/阈值,控制样例查询在本智能体上是否启用:

样例查询开关(sampleQueryEnabled)

是否启用样例优先匹配。

默认关闭(禁用)
启用后,用户提问会先去样例库做向量匹配,命中则直接返回标准答案,零 LLM 调用

匹配阈值(sampleQueryThreshold)

相似度 ≥ 此值才算命中样例。

默认 0.85,范围 0 ~ 1,步进 0.05
阈值越高匹配越严格(误命中少,但可能漏匹配)
留空则回退全局配置(在「样例查询」管理页设置,默认 0.85)
样例需先在「样例查询」中向量化后才可被匹配

💡 这一项的完整原理和价值见样例查询,这里只是开关和阈值。

5.5 检索

控制"怎么从知识库找内容",直接决定检索质量,是最需要调参的部分。

检索方式(retrievalMode)

用哪种方式从知识库召回内容,默认 mix。

方式	说明	适用场景
mix(默认)	向量 + 关键词加权融合	✅ 推荐,召回最全
embedding	仅语义向量召回	语义模糊匹配(用户表述多变)
text	仅关键词全文检索	精确词面命中(如专有名词、编号)

向量召回 topK(embeddingTopK)

向量检索返回多少条候选。

默认 10,范围 1 ~ 50
值大:召回多、漏答少,但引入噪音、费 token
值小:精准省 token,但可能漏掉答案
配合重排时可适当调大(海选多一些,重排精筛)

向量相似度阈值(vectorThreshold)

只保留向量相似度 ≥ 此值的结果。

默认 0.2,范围 0 ~ 1,步进 0.05
过高 → 检索为空,智能体无内容可答
过低 → 大量无关内容混入,干扰回答

关键词阈值(keywordThreshold)

关键词检索通道的相关性门槛,和向量阈值同理。

默认 0.3,范围 0 ~ 1,步进 0.05
用于 mix 模式下的关键词通道,过滤掉词面命中但实际不相关的内容

启用重排(rerankEnabled)

是否对召回结果做重排精排。

默认启用
开启后效果通常更好,但需要配好重排模型

重排模型(rerankModelKey)

选哪个重排模型做精排。

留空则用系统默认重排(基于向量相似度)
下拉同样会把多模型名拆成子选项
必须先在模型配置里配好重排模型才能选

重排 topK(rerankTopK)

重排后最终保留几条喂给模型。

默认 5,范围 1 ~ 30
值小:只留最精华的,精准省 token
值大:保留更多上下文,信息更全但易稀释

重排阈值(rerankThreshold)

重排相关性低于此值的结果被丢弃。

默认 0.3,范围 0 ~ 1,步进 0.05
进一步过滤重排后的低质量结果

⚠️ 检索参数注意事项:

🔴 阈值不是越高越好!很多人误以为"阈值高 = 更精准",其实过高会导致检索为空,智能体反而答不出
🟢 几个参数要协同调整:topK 控数量、阈值控质量、重排做精筛
💡 调参顺序:先定检索方式(mix)→ 调 topK → 向量/关键词阈值 → 重排参数
💡 改了立即生效,不需要重新入库

5.6 兜底

当检索不到内容、或模型调用失败时,怎么"兜底"回答,避免直接报错或胡说。

兜底策略(fallbackStrategy)

两种兜底方式二选一,默认 model。

策略	说明
model(默认)	模型兜底:检索不到时,仍让模型基于自身能力回答(配合提示词约束)
fixed	固定回复:直接返回一句预设话术

兜底话术(fallbackResponse)

选了 fixed 策略后才会出现,填写固定回复内容。

示例:抱歉,暂未找到相关信息,请联系人工客服。
当知识库无法召回时,直接返回这段话

⚠️ 注意事项:

✅ 生产环境强烈建议配好兜底:最怕"裸奔",检索为空时给用户一个体面的回应
🔴 不配兜底 + 检索为空 → 模型可能编造答案(幻觉),这是 RAG 最忌讳的
💡 固定话术要诚实:查不到就说查不到,别让模型硬编

5.7 参数速查表

标签页	参数	默认值	作用
基础	知识库模式	指定	控制数据来源
基础	对话模型	系统默认	思考与回答
提示词	系统提示词	知识库默认模板	角色与规则
模型参数	温度	0.3	回答随机性
模型参数	最大生成 token	2048	回答长度上限
模型参数	记忆轮数	4	多轮上下文
模型参数	意图/改写模型	同对话模型	降本提速
样例查询	开关 / 阈值	关 / 0.85	标准问题直返
检索	检索方式	mix	召回策略
检索	向量 topK	10	向量召回数量
检索	向量阈值	0.2	向量过滤
检索	关键词阈值	0.3	关键词过滤
检索	重排开关	启用	是否精排
检索	重排 topK	5	重排保留数量
检索	重排阈值	0.3	重排过滤
兜底	兜底策略	model	异常处理方式

创建第一个智能体

1. 目标

2. 登录项目

3. 配置大模型

3.1 对话模型(Chat Model)

3.2 向量模型(Embedding Model)

3.3 重排模型(Rerank Model)

3.4 视觉模型(Vision Model)

3.5 四类模型协作关系

3.6 配置建议速查

3.7 以对话模型为例子

模型名字

API 秘钥

可用模型(多个用逗号隔开)

接口地址

温度(Temperature)

最大输出(Max Tokens)

测试

4. 创建知识库

4.1 知识库名称

4.2 向量模型

⚠️ 注意事项:向量模型创建后不可更改

4.3 上传文档

4.3.1 各类文档的解析策略

纯文本类(README / 日志 / 代码 / 配置等)

Office 文档(Word / Excel / PowerPoint)

标准 PDF(可复制文字的电子版)

扫描件 PDF / 图片型文档(需要 OCR)

复杂版面 PDF(多栏 / 公式 / 图文混排) —— MinerU 登场

4.3.2 解析策略总览

4.4 MinerU 详解

4.4.1 MinerU 是什么

4.4.2 普通 PDF 解析器解决不了的问题

4.4.3 MinerU 用在哪里

4.4.4 MinerU 解决了哪些问题

4.4.5 要不要启用 MinerU

4.5 切割文档

4.5.1 为什么要切割

4.5.2 切割策略

固定长度切割(Fixed Size)

结构化切割(Structural / 版面感知)

父子分块(Parent-Child)—— 重点推荐

按行切分(Spreadsheet Row)

4.5.3 切割大小建议

不同场景的调整方向

三个判断信号

4.5.4 父子分块详解

它解决什么矛盾

工作原理

效果对比

什么时候开 / 关

4.5.5 切割参数速查表

4.6 预览分块

4.7 向量化

5. 创建智能体

5.1 基础

名称(必填)

描述(可选)

知识库

对话模型

状态

5.2 提示词

系统提示词

编写要点

开场白

推荐问题

5.3 模型参数

温度(temperature)

最大生成 token(maxTokens)

记忆轮数(historyTurns)

意图/改写模型(rewriteModelKey)

5.4 样例查询

样例查询开关(sampleQueryEnabled)

匹配阈值(sampleQueryThreshold)

5.5 检索

检索方式(retrievalMode)

向量召回 topK(embeddingTopK)

向量相似度阈值(vectorThreshold)

关键词阈值(keywordThreshold)

启用重排(rerankEnabled)