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

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

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

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

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

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

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

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

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，便于按问答场景统计成本。
• 轻量模型用于改写问题、提取***和短摘要。
• 强模型用于最终答案生成或复杂推理。
• 上下文长度必须设上限，不要无限塞检索结果。

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

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

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

四、后端封装示例：业务只调用 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 的费用来自检索后多轮处理 💰

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

建议先用真实问题样本跑一轮预算压测，记录平均检索片段数、输入长度、输出长度和失败率，再决定默认模型组合。

九、上线前验收清单 ✅

• 1️⃣ 知识库已按公开、内部、技术、敏感资料分层。
• 2️⃣ 检索阶段已做权限过滤，不让无权限资料进入上下文。
• 3️⃣ RAG 服务单独使用 Key，便于统计问答成本。
• 4️⃣ 检索、重排、压缩、生成四步都有日志。
• 5️⃣ 最终答案带引用编号，并能反查到原始文档。
• 6️⃣ 资料不足时会明确说明，不编造答案。
• 7️⃣ 上下文长度有上限，检索片段会去重和裁剪。
• 8️⃣ 已用真实问题样本完成成本和质量压测。

知识库接入的价值，不是把文档都丢给模型，而是让模型基于正确、可追溯、权限合规的资料回答。统一模型入口、做好检索边界和引用审计后，RAG 才能从“能答”变成“可信”。🚀

本文配图来自本地重新截取公开页面，用于说明知识库/RAG 接入流程；示例 Key 均为占位符。