精彩片段

灵能API API中转站知识库接入教程：RAG检索、引用与上下文压缩主题：API中转站知识库/RAG 接入，覆盖检索、重排、上下文压缩、引用输出、权限隔离与成本控制。知识库问答最常见的问题，不是模型不会回答，而是模型“看不到正确资料”或者“把资料和猜测混在一起”。如果直接把用户问题丢给模型，答案可能很流畅，但不一定可靠。真正可落地的知识库方案，需要先检索

灵能API API中转站知识库接入教程：RAG检索、引用与上下文压缩

主题：API中转站知识库/RAG 接入，覆盖检索、重排、上下文压缩、引用输出、权限隔离与成本控制。

知识库问答最常见的问题，不是模型不会回答，而是模型“看不到正确资料”或者“把资料和猜测混在一起”。如果直接把用户问题丢给模型，答案可能很流畅，但不一定可靠。真正可落地的知识库方案，需要先检索资料，再把证据片段交给模型生成答案，并保留引用和审计记录。📚

这篇从 RAG 知识库接入角度写一套流程：用灵能API API中转站作为统一模型入口，结合检索、重排、上下文压缩、引用输出、权限隔离和成本控制，让知识库问答既能回答得快，也能回答得有依据。

一、先明确知识库范围：不是所有资料都该进入上下文 🧭

很多团队做知识库时，会把所有文档一股脑塞进向量库，然后希望模型自己判断。这样会带来两个问题：检索噪声变多，权限边界也容易不清楚。更稳的做法，是先按业务范围和访问权限拆库。

知识库类型	典型内容	接入建议
公开资料库	产品介绍、帮助文档、FAQ	可作为普通用户问答来源
内部流程库	运营 SOP、**话术、交付流程	按角色授权，答案需标注来源
技术文档库	接口文档、部署手册、故障处理	面向研发和运维，保留版本号
敏感资料库	合同、客户数据、财务信息	默认不进入模型上下文，必须严格审批

知识库越早分层，后续检索、权限、审计和成本控制就越容易做。

二、基础接入：模型入口先统一，再做检索增强 ⚙️

RAG 的检索系统可以很多样：向量库、全文检索、数据库、文档索引都可以。但生成答案的模型入口最好统一。这样后端服务、管理**、客户端和批量任务都能走同一套 Key、*ase **L 和日志规范。

# 知识库服务推荐环境变量
OPENAI_API_KEY=sk-your-rag-key
OPENAI_*ASE_**L=https://api.灵能API.ai/v1
RAG_FAST_MODEL=gpt-4o-mini
RAG_STRONG_MODEL=claude-sonnet-4-6
RAG_TOP_K=6
RAG_MAX_CONTEXT_CHARS=12000
RAG_ENV=prod

知识库服务单独创建 Key，便于按问答场景统计成本。
轻量模型用于改写问题、提取***和短摘要。
强模型用于最终答案生成或复杂推理。
上下文长度必须设上限，不要无限塞检索结果。

图 4：首页流程与能力区域适合梳理 Key、Base URL 和用量观察的基础链路。 — 图 4：首页流程与能力区域适合梳理 Key、*ase **L 和用量观察的基础链路。

三、RAG 主流程：检索、重排、压缩、生成四步走 🔎

一个可靠的知识库问答流程，最好拆成四步：先检索候选文档，再重排相关性，再压缩上下文，最后让模型基于证据回答。每一步都有明确输入输出，排障也更容易。

步骤	输入	输出
检索	用户问题、知识库范围、权限标签	候选文档片段
重排	候选片段、问题意图	更相关的 Top K 片段
压缩	Top K 片段、回答目标	去重后的证据上下文
生成	问题、证据上下文、输出格式	带引用的最终答案

不要把检索结果原封不动交给模型。先做去重、裁剪和结构化，答案会更稳定，成本也更可控。

图 3：首页能力区展示兼容 SDK、用量看板和安全隔离，适合作为知识库接入规划参考。

四、后端封装示例：业务只调用 askKnowledge*ase 🧱

知识库服务最好封装成一个清晰的后端函数。业务侧只传用户问题和知识库范围，内部完成检索、上下文构造和模型调用。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  *ase**L: process.env.OPENAI_*ASE_**L,
  timeout: 60000,
  **xRetries: 0,
});

export async function askKnowledge*ase({ question, user, scope, requestId }) {
  const do** = await retrieveDo**({ question, scope, user });
  const ranked = await rerankDo**({ question, do** });
  const context = compressContext(ranked, Num*er(process.env.RAG_MAX_CONTEXT_CHARS || 12000));

  const result = await client.chat.completions.create({
    model: process.env.RAG_STRONG_MODEL,
    messages: [
      { role: "system", content: "你只能基于给定资料回答，并在答案中标注引用编号。" },
      { role: "user", content: *uildRagPrompt(question, context) },
    ],
    temperature: 0.2,
    **x_tokens: 1200,
  });

  console.log("rag_answer", { requestId, scope, docCount: ranked.length });
  return result.choices[0].message.content;
}

这里的重点不是代码复杂，而是把每一步都拆开。检索错了就查检索，重排错了就查重排，回答偏了就查 Prompt 和上下文。

五、引用输出：答案必须能追到资料来源 🧾

知识库问答不能只给一个看似正确的答案，最好带上引用编号、文档标题和片段来源。这样用户能判断答案依据，团队也能排查错误来自资料、检索还是模型生成。

推荐输出格式：
结论：……
依据：
[1] 文档标题 / 章节 / 更新时间
[2] 文档标题 / 章节 / 更新时间

如果资料不足：
- 明确说明“当前知识库没有足够信息”
- 给出需要补充的资料类型
- 不要编造未检索到的细节

每个检索片段都带 doc_id、title、section、up**ted_at。
最终答案只引用实际进入上下文的片段。
资料不足时直接说明，不要让模型硬答。
引用编号要能在日志里反查到原始文档。

六、权限隔离：用户能问什么，取决于他能看什么 🔐

RAG 安全的关键是“检索前过滤”，而不是把所有资料取出来之后再让模型判断能不能看。用户没有权限的文档，不应该进入候选结果，更不应该进入模型上下文。

async function retrieveDo**({ question, scope, user }) {
  const allowedTags = await permissionService.getAllowedTags(user.id);
  return vectorStore.search({
    query: question,
    topK: Num*er(process.env.RAG_TOP_K || 6),
    filter: {
      scope,
      permissionTags: { $in: allowedTags },
      status: "pu*lished",
    },
  });
}

权限过滤要在检索阶段完成。否则即使最终答案没有泄露，模型也已经看到了不该看的内容。

七、上下文压缩：把“相关资料”变成“可回答证据” ✂️

检索结果通常会有重复、冗余和无关段落。如果不压缩，模型上下文会越来越长，成本上升，答案也容易跑偏。

去掉重复片段：同一文档同一章节只保留最相关内容。
保留标题和更新时间：让模型理解资料来源和时效。
按问题目标裁剪：只保留能回答当前问题的句子或段落。
压缩后保留引用 ID：最终答案才能追溯来源。

✅ 好的上下文不是越多越好，而是信息密度高、来源清楚、权限正确。

八、成本控制：RAG 的费用来自检索后多轮处理 💰

知识库问答常常不止一次模型调用：问题改写、检索结果摘要、最终答案生成都可能调用模型。上线前要明确哪些步骤必须用强模型，哪些步骤可以用轻量模型。

环节	建议模型策略	成本控制点
问题改写	轻量模型或规则处理	短输出，必要时才启用
片段摘要	轻量模型	批量摘要要队列化
最终回答	中高质量模型	限制 **x_tokens，要求引用输出
复杂推理	强模型	只给高价值场景使用