CNB 文档

简体中文

English

简体中文

English

外观

知识库

复制页面

2050 字约 7 分钟

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

将文档提交到仓库并配置知识库流水线后，系统自动完成文档切片、 分词、向量化等处理，把内容写入知识库，供页面问答、Open API 等场景调用， 快速构建 RAG（Retrieval-Augmented Generation，检索增强生成）应用。

知识准备

了解构建 RAG 应用的流程

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

通过云原生构建知识库插件 2 步构建 RAG 应用流程图
通过云原生构建知识库插件 2 步构建 RAG 应用流程图

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

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

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

知识库构建完成后，可通过云原生构建 Open API 召回相关文档，再结合 LLM 模型生成最终回答。

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

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

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

请根据以上知识库，回答用户的问题。
  1. 将拼接后的 Prompt 发送给 LLM 模型，生成回答并返回给用户。

具体使用方法

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

在 .cnb.yml 中配置流水线，使用知识库内置任务。当仓库的 main 分支有代码提交时，会触发流水线， 自动对文档、Issue 等内容切片、分词、向量化，并把结果写入知识库。

以下为最简单的配置示例，仅指定需要包含的文件类型：

.cnb.yml
main:
  push:
    - stages:
        - name: build knowledge base
          type: knowledge:update
          options:
            include: "**/**.md"
            # exclude: ["node_modules/**", "dist/**"]       # 排除无需索引的目录
            # issueSyncEnabled: true                          # 同步 Issue 数据（默认开启）
            # chunkSize: 1500                                 # 分块大小（默认 1500）

部分内置任务参数说明如下。更多内容请阅读 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);

AI 对话中启用知识库

知识库构建完成后，可在仓库页面的 AI 对话中启用知识库，让 AI 基于仓库文档进行问答。

如果需要进一步增强体验，还可通过 .cnb/settings.yml UI 定制配置文件 个性化定制：

  • 引入其他仓库配置
  • 定义不同的 AI 角色
  • 定制知识库按钮样式
  • 设置默认仓库和默认角色

以上功能均通过 .cnb/settings.yml 中的 npc 配置段实现：

  • npc.imports.list：引入其他仓库知识库
  • npc.roles：定义 AI 角色，例如：
    • 资浅工程师：用简单易懂的方式解释概念
    • 资中工程师：提供专业的技术解答
    • 资深工程师：解决复杂技术问题，并提供架构设计和深度见解
  • npc.button：知识库按钮的名称、描述和悬浮图片
  • npc.defaultRepo / npc.defaultRole：默认仓库和默认角色

详细配置语法请参考 UI 定制配置文件。

评论中 @AI 角色

在 AI 角色所属仓库的默认分支下，可以在 .cnb.yml 中定义 AI 角色被 @ 时触发的流水线配置。

在其他仓库的 Issue 或 PR 评论中，也可以 @ NPC 中定义的 AI 角色。 此时会触发 NPC 事件，云原生构建 会引用上述 .cnb.yml 文件 作为当前 NPC 事件的流水线配置。

例如在 AI 角色所属仓库的 .cnb.yml 中，为 issue.comment@npc 事件配置流水线：

.cnb.yml
$:
  issue.comment@npc: # Issue/PR 评论中 @ 当前 AI 角色时触发
    - docker:
        image: cnbcool/cnb-ai:latest
      stages:
        - name: 调用知识库回答
          script: cnb ai chat --repo $CNB_REPO_SLUG --role 资深工程师

更多详细信息，请参考 NPC 事件。

© 2026 cnb.cool