---
url: /zh/ai/knowledge-base.md
description: |
  介绍如何通过代码仓库快速搭建企业或个人知识库，配置知识库流水线插件，构建 RAG（检索增强生成）应用， 并通过 Open API 检索知识。
---
通过代码仓库可以快速搭建企业或个人知识库。

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

## 知识准备

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

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

![通过云原生构建知识库插件 2 步构建 RAG 应用流程图](/images/ai/cnb-knowledge-base-rag.png)

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

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

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

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

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

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

```text
用户提问：{用户问题}

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

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

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

## 具体使用方法

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

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

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

```yaml title=".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](../build/internal-steps/knowledge/update.md) 内置任务文档。

* `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 使用教程](../develops/openapi.md)。

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

::: tip 提示
`{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 请求示例：

```bash
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`，匹配相关性分数，值越高表示匹配度越高。

响应示例：

```json
[
  {
    "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` 应用示例：

```js
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 定制配置文件](../repo/settings.md) 个性化定制：

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

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

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

详细配置语法请参考 [UI 定制配置文件](../repo/settings.md)。

### 评论中 @AI 角色

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

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

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

```yaml title=".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 事件](../build/trigger-rule.md#npc-事件)。