配置与软约定

类型系统能保证字段形状，却保证不了这些值是否合理：目录里放哪份资料、预算取多少、候选留几条、日志记什么、密钥从哪里来。这些是软约定，需要显式管理，否则问题会在运行期以“回答变差”而不是“配置错误”的形式出现。

什么不受类型保护

配置	风险	建议
资料目录与文件命名	文件被移动或漏加载，空资料被当成正常	启动时校验目录、id 与 revision
主题词表与别名	新说法召回不到	把真实未命中问题补进词表
预算与候选数量	调得过紧会拒绝，过松会挤掉规则	按真实调用测量后调整
提示词与领域规则文本	语义漂移，无法由编译发现	版本化，保留变更依据
日志字段	缺字段无法归因，多字段泄露隐私	先定字段，再定保留期
环境变量与密钥	提交泄露、环境混用	只从环境或密钥服务读取

SDK 强制的边界

SDK 会拒绝越界值，但不替你选择业务值。已知边界包括：

• TextSearch 与 VectorSearch 的 limit 为 1—1000，过滤函数必须同步返回布尔值；
• VectorSearch 的 dimensions 为 1—16384，minScore 在 -1—1，零向量会被拒绝；
• TextSearch 的查询不能为空，字段与存储字段必须在构造时声明；
• Knowledge 的 maxChars 与上下文片段上限由 App 设置，超限直接报错；
• ModelCalls 的 timeoutMs 必须是支持范围内的正安全整数。

这些是合同，不是建议。业务预算、候选数量和超时值仍由 App 决定。

推荐起点

下面的数值是起点，不是标准答案。先用真实调用测量，再决定是否调整。

项目	起点建议	调整依据
资料读取	优先整篇；单次读取不超过模型输入的约三分之一	超出后分主题或章节读取
检索候选	关键词与向量各取 20，融合后保留 5—8 条	看 recall@k 与上下文占用
模型调用超时	短于请求总期限，并为重试留余量	供应商延迟分布与取消需求
embedding 超时	独立于模型调用，失败可降级	检索是否可退回关键词
日志保留	按隐私与排障需要分别设定	不照搬示例或临时值
索引重建	内容 revision 变化时增量更新	分词、字段或模型变化时全量重建

预算不要调到刚好卡住当前样本。轻微增长就触发拒绝，会让系统在真实使用中显得不可靠。

启动自检

启动时做一次只读检查，失败就明确拒绝启动或关闭对应能力：

• 资料目录存在、文件可读、catalog 可解析；
• 文档与章节 id 唯一，revision 非空；
• 内部链接、来源与 scope 引用有效；
• 允许空资料，但空资料不能被当成“已加载”；
• embedding 模型 identity 与索引空间一致；
• 配置版本与实际生效值可被记录到日志。

自检只证明结构和引用，不证明内容真实或语义正确。

命名与版本

• 文档、章节和块使用稳定 id；标题可以改，身份不要跟着改。
• revision 使用内容哈希或明确的发布号；同一 revision 不应对应两份不同正文。
• TextSearch.indexRevision 在字段、分词或归一化规则变化时更新，否则旧快照会被错误恢复。
• 检索配置使用独立标识，并随每次请求记录；否则无法把“回答变差”归因到某次配置调整。
• 资料更新走候选与发布流程；不要在运行目录手改后假装版本未变。

密钥与环境

• 模型、embedding 与存储凭据只从环境变量或密钥服务读取，不写入资料、提示词或仓库。
• 不同环境使用不同凭据与索引，不共享测试数据。
• 日志不输出密钥、完整提示词和未脱敏个人资料。
• 客户端传入的配置只能作为数据，不能提升权限或改变模型连接。

变更方式

配置变更也需要证据：改了什么、为什么改、在哪些样本上观察、失败时怎么退回。没有测量记录的“优化”不要直接进入正式环境。

生成目录、运行副本和构建产物不要手改。修改源稿或配置源，再重新生成；否则下一次构建会覆盖修改，且差异无法解释。

常见问题

现象	可能原因	处理
启动正常但回答总说没有资料	目录未加载或空资料被当成正常	加启动自检与加载结果日志
更新资料后仍回答旧内容	revision 未变或缓存未清	重新生成 revision，清理索引与缓存
预算偶尔拒绝	取值贴近当前样本上限	留余量，或分次读取
更换模型后检索异常	embedding 空间不一致	校验 identity，重建索引
日志无法定位问题	缺配置标识、阶段或工具 ID	先补字段，再排查

下一步

• 需要资料与索引的具体搭法：RAG 资料搭建。
• 需要判断配置调整是否有效：检索质量评估。
• 需要发布前逐项确认：上线前的软性检查。