本地调通一个大模型 API 只说明网络和参数基本可用。接进真实业务后，首字延迟、半截 JSON、429、取消和重复执行都要处理：
{"answer": "根因是。客服 RAG 升级混合检索和 Reranker 后，最容易出现的上线判断是：本地挑几十条问题跑一遍，答案比旧版顺，就觉得可以放量。
如果放量一周后业务方只反馈“有些问题感觉还不如以前准”，排查会立即卡住。
这时需要回看同一批场景的历史结果：旧版本在退换货、物流查询、商品参数对比上的命中率分别是多少，新版本又是从哪一类问题开始退步的。没有这份基线，“不如以前准”既可能是质量回退，也可能只是用户预期变化；排查最终只能回到原始对话里逐条翻找。
模型选择、Prompt 调整、检索优化和灰度发布会因此失去共同的比较口径。评测集的作用，就是把这些改动放到同一把尺子下比较。
温度已经设为 0，结构化输出仍可能解析失败；上下文塞满文档后，模型也可能漏掉中间位置的关键约束。这些现象需要从 Token 切分、上下文容量和解码策略分别排查。
排查这些问题，要先看一次调用由哪些 Token 组成，再核对上下文预算以及 Temperature、Top-p、Top-k 等解码参数。文中的 Token 数和参数范围只用于解释机制，实际计费与能力上限仍以目标模型的 API 文档和响应 usage 为准。
当你在输入法里打“今天天气真”，它会自动建议“好”。大模型同样在预测后续内容，只不过它参考的是前面几千甚至几十万个字。每次生成一个 Token（文本碎片），再把它加入上下文并预测下一个，直到回答结束。
Prompt 里写一句“请返回 JSON”，模型通常能吐出一个对象，但这份对象还不能直接当业务接口使用。
有时它会在 JSON 前面加一句“好的，以下是结果”；有时少一个必填字段；有时本来应该是数字的 orderId 变成字符串；更麻烦的是，边界条件一复杂，模型会补出一个业务系统根本不认识的枚举值。解析器一报错，整条链路就断了。
自然语言提示没有类型系统，也不能执行权限校验。结构化输出把字段、类型和枚举交给 Schema 约束；Function Calling 再把模型生成的工具意图交给可信执行层校验。JSON Mode、Structured Outputs、MCP 与 Java 服务端分别处在这条调用链的不同位置。
“这几个部门过去半年反复提到的风险点是什么，它们之间有什么关联？”这类问题需要跨文档汇总部门、风险、项目、供应商和时间信息。Top-K 向量检索可以找出相似片段，但不会自动保存这些对象之间的关系。
GraphRAG 在检索链路中加入图结构，用实体、关系或主题摘要组织跨文档证据。是否值得引入，要看现有 RAG 的失败样本是否集中在多跳关系和全局归纳上。
做企业知识库问答时，很多团队的第一反应都是：把文档全塞给大模型，让它自己读。
文档少的时候，这招确实能跑。一旦知识库涨到几十万字，问题很快就出来了：每次请求都可能撞 Token 上限，刚更新的内容模型也不一定知道。更现实一点，企业文档还要考虑权限、溯源、成本和延迟，不能靠“全塞进去”硬扛。
RAG 会在模型回答前从知识库中检索相关内容，再把这些内容交给模型，让回答尽量落在可核对的证据上。检索、上下文组织和生成任一环节出错，最终答案都可能偏离原文。
RAG（Retrieval-Augmented Generation，检索增强生成） 就是把信息检索和大语言模型绑在一起用。系统先从知识库里检索出和当前问题相关的片段，知识库可以是数据库、文档集合，也可以是企业内部系统。然后把这些片段和原始问题一起喂给 LLM，让模型基于检索内容回答，而不是只靠训练时记住的知识。
RAG 检索前要先把 PDF、Word、Excel 或扫描件转换成可检索内容。多栏 PDF 的阅读顺序、表格的行列关系、标题层级和 OCR 错误如果在这一步处理错了，后续更换 Embedding 模型或向量数据库也无法恢复丢失的信息。
本文会依次说明文档上传、解析、切分、校验和多模态入库的做法与限制。
术语约定：本文中 "Chunking" 与“切分”、"Embedding" 与“嵌入”、"Chunk" 与“块” 含义相同，统一使用中文表述以保持可读性。
第一个企业知识库 RAG 系统上线后，很多团队都会碰到一个很真实的问题：文档明明更新了，回答还是老样子。
这时候先别急着怪 LLM。更常见的原因是知识库没有同步更新，或者更新链路只做了“写入新内容”，没有处理旧版本、权限、索引一致性这些细节。
文档变更频繁之后，问题会更明显：每次都全量重建索引，成本和耗时扛不住；只更新变化部分，又怕漏掉旧块；只插入新向量，不清理旧版本，过期内容还会继续被召回；换了 Embedding 模型，历史数据到底要不要全部重索引，也绕不开。
知识库更新要同时处理版本、权限和多个索引之间的一致性。本文沿着新增、修改、删除三类事件，说明增量同步、全量重建、灰度、回滚和监控怎么配合。
RAG 答错时，直接更换 Embedding 模型或扩大 Top-K 很难稳定解决问题。PDF 表格解析错误、Chunk 切断条件、权限过滤过晚、候选池缺少正确证据，都会让生成模型拿到错误上下文。
调优时要沿着文档、索引、召回、重排、上下文和生成逐段定位，再用固定评测集回放改动。
RAG 更像一条证据加工流水线：原始资料先被解析、清洗、切块、打标签、建索引；用户问题进来后，再经过查询理解、召回、重排、上下文构建，最后才交给 LLM 生成答案。
这条链路里任何一环出问题，都会传染到下游。
| 环节 | 典型问题 | 最终表现 |
|---|---|---|
| 文档解析 | 表格错位、标题丢失、页码缺失 | 答案引用不准，关键条件丢失 |
| Chunk 切分 | 块太大、太小、语义边界被切断 | 召回噪声大，或者召回片段缺上下文 |
| Metadata | 没有保存来源、时间、权限、章节 | 无法过滤，无法引用，容易越权 |
| 召回 | 只用向量检索，忽略关键词和结构化条件 | 错过错误码、SKU、版本号、专有名词 |
| 重排 | 直接把 Top-K 塞给模型 | 正确片段排在后面，模型看不到重点 |
| 上下文 | 不去重、不压缩、不排序 | Token 浪费，模型被噪声干扰 |
| 生成 | Prompt 没有限定证据边界 | 答案看起来流畅，但引用和事实对不上 |
| 评估 | 只看主观体验，不建测试集 | 改动靠感觉，线上反复回退 |
把 Embedding 存进普通字段并逐条计算距离，数据量小时可以作为精确检索基线。数据规模、并发或延迟要求上升后，全表扫描的计算开销会随向量数量线性增长，此时需要评估 ANN 索引或专门的向量检索系统。
本文从距离度量和索引算法讲起，再结合 PostgreSQL + pgvector 说明 HNSW、IVFFLAT 的参数、过滤行为和选型方法。
向量数据库并不是直接理解文本。它存储和检索的是 Embedding。
Embedding 的过程是：把一段文本交给 Embedding 模型，模型输出一个固定维度的稠密向量。可以粗略理解成“文本语义坐标”。两段文本语义越接近，它们在向量空间里的距离通常也越近。