知识库

2221 字约 7 分钟

通过代码仓库，你可以快速搭建企业或个人知识库。

只需将文档上传到仓库，并配置知识库相关流水线，系统就会自动处理文档内容并通过大模型写入知识库。处理后的知识库可供页面问答、Open API 等场景调用，用于快速构建 RAG（Retrieval-Augmented Generation，检索增强生成）应用。

知识准备

了解构建 `RAG` 应用的流程

下图展示了如何通过 云原生构建 的知识库插件，用 2 个步骤构建一个 RAG 应用。

1. 使用知识库插件将仓库内容导入知识库

使用 云原生构建 知识库插件后，仓库中的文档、Issue 等内容会被自动导入知识库。

插件运行在云原生构建流水线中，会自动完成文档切片、分词、向量化等处理。知识库构建完成后，即可被下游的 LLM 应用直接使用。

2. 调用云原生构建 Open API 检索并生成回答

知识库构建完成后，可以通过云原生构建的 Open API 进行召回，再结合 LLM 模型生成最终回答。

一个常见的 RAG 应用运行流程如下：

用户提问。
理解用户问题后，使用 Query 调用知识库检索，获取相关文档片段。
拿到检索结果后，将“用户问题 + 知识上下文”拼接为 Prompt，例如：

用户提问：{用户问题}

知识库：
{从知识库检索到的内容}

请根据以上知识库，回答用户的问题。

将拼接后的 Prompt 发送给 LLM 模型，生成回答并返回给用户。

具体使用方法

步骤 1：在流水线中使用知识库内置任务

在代码仓库的 .cnb.yml 中配置流水线，并使用知识库内置任务。

如下例所示，当仓库的 main 分支有代码提交时，会触发流水线。流水线会自动对仓库中的文档、Issue 等内容进行切片、分词、向量化等处理，并将处理后的内容上传到知识库。

.cnb.yml
main:
  push:
    - stages:
        - name: build knowledge base
          type: knowledge:update
          options:
            include: "**/**.md"

部分内置任务参数说明如下。更多内容请阅读 knowledge:update 内置任务文档。

include：指定需要包含的文件，使用 Glob 模式匹配，默认为 **/**.md，支持数组或逗号分隔
exclude：指定需要排除的文件，使用 Glob 模式匹配，默认不排除任何文件，支持数组或逗号分隔
chunkSize：指定文本分块大小，默认为 1500
chunkOverlap：指定相邻两个分块之间的重叠 token 数量，默认为 0
embeddingModel：嵌入模型，默认为 hunyuan，目前仅支持 hunyuan
issueSyncEnabled：是否启用 Issue 同步功能，默认为 true，启用后会自动拉取仓库的 Issue 数据并加入知识库
issueState：仅同步指定状态的 Issue，默认包含全部，可选值为 open | closed
issueLabels：仅同步指定标签的 Issue，默认包含全部，支持数组或逗号分隔
issueExcludeLabels：排除带有指定标签的 Issue，默认不排除，支持数组或逗号分隔。当与 issueLabels 存在交集时，exclude 优先
forceRebuild：是否删除知识库并重新构建，默认为 false
ignoreProcessFailures：是否忽略文档处理失败，默认为 false，设置为 true 时即使有文件处理失败也会更新知识库

步骤 2：通过 Open API 使用知识库

知识库构建完成后，可以通过 Open API 对该仓库所属的知识库进行查询检索，召回后的内容可以进一步结合 LLM 模型生成回答。

开始之前，请先阅读：CNB Open API 使用教程。

访问令牌需要具备 repo-code:r 权限（仓库读权限）。

提示

{slug} 需要替换为仓库 slug。

例如，官方文档知识库的仓库地址为 https://cnb.cool/cnb/feedback，则 {slug} 对应 cnb/feedback。

接口信息

URL：https://api.cnb.cool/{slug}/-/knowledge/base/query
方法：GET

请求参数

通过 URL Query String 传递以下参数：

query：String，必填，要查询的关键词或问题。
top_k：Number，默认 5，返回结果的最大数量。
score_threshold：Number，默认 0，匹配相关性分数阈值。

cURL 请求示例：

curl -G "https://api.cnb.cool/cnb/feedback/-/knowledge/base/query" \
  -H "accept: application/json" \
  -H "Authorization: Bearer ${token}" \
  --data-urlencode "query=云原生开发配置自定义按钮"

响应内容

响应为 JSON 格式，包含一个结果数组。每个结果包含以下字段：

score: Number，匹配相关性分数，范围 0-1，值越高表示匹配度越高。
chunk: String，匹配的知识库内容文本。
metadata: Object，内容元数据。

metadata 字段详情如下：

hash: String内容的唯一哈希值。
name: String，文档名称。
path: String，文档路径。
position: Number，内容在原文档中的位置。
score: Number，匹配相关性分数，值越高表示匹配度越高。

响应示例：

[
  {
    "score": 0.8671732,
    "chunk": "该云原生远程开发解决方案基于Docker...",
    "metadata": {
      "hash": "15f7a1fc4420cbe9d81a946c9fc88814",
      "name": "vscode",
      "path": "docs/vscode.md",
      "position": 0,
      "score": 0.8671732,
      "type": "code",
      "url": "https://cnb.cool/cnb/docs/-/blob/3f58dbaa70ff5e5be56ca219150abe8de9f64158/docs/vscode.md"
    }
  }
]

拿到响应结果后，即可结合 LLM 模型生成回答。

`RAG` 小应用示例

下面是一个使用 JavaScript 实现的简易 RAG 应用示例：

import OpenAI from 'openai';

// 配置
const CNB_TOKEN = 'your-cnb-token'; // 替换为你的 CNB 访问令牌, 需要权限：`repo-code:r`
const OPENAI_API_KEY = 'your-openai-api-key'; // 替换为你的 OpenAI API 密钥
const OPENAI_BASE_URL = 'https://api.openai.com/v1'; // 或者你的代理地址
const REPO_SLUG = 'cnb/feedback'; // 替换为你的仓库 slug

// 初始化 OpenAI 客户端
const openai = new OpenAI({ 
  apiKey: OPENAI_API_KEY,
  baseURL: OPENAI_BASE_URL
});

async function simpleRAG(question) {
  // 1. 调用 CNB 知识库检索
  const params = new URLSearchParams({ query: question });
  const response = await fetch(`https://api.cnb.cool/${REPO_SLUG}/-/knowledge/base/query?${params}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${CNB_TOKEN}`
    }
  });
  
  const knowledgeResults = await response.json();
  
  // 2. 提取知识内容（这里假设取全部结果）
  const knowledge = knowledgeResults
    .map(item => item.chunk)
    .join('\n\n');
  
  // 3. 调用OpenAI生成回答
  const completion = await openai.chat.completions.create({
    model: "gpt-4.1-2025-04-14",
    messages: [
      {
        role: "user",
        content: `问题：${question}\n\n知识库：${knowledge}\n\n请根据知识库回答问题。`,
      },
    ],
  });

  return completion.choices[0].message.content;
}

// 使用示例
const answer = await simpleRAG("如何开发一个插件？");
// 输出结合知识库的回答
console.log(answer);