---
url: /zh/ai/knowledge-base.md
---
通过代码仓库，你可以快速搭建企业或个人知识库。

只需将文档上传到仓库，并配置知识库相关流水线，系统就会自动对文档内容进行大模型处理后写入知识库，供页面问答、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"
```

部分内置任务参数说明如下。更多内容请阅读 [knowledge:update](../build/internal-steps/README.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 使用教程](../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`
* **方法**：`POST`
* **内容类型**：`application/json`

### 请求参数

请求体为 JSON 格式，包含以下字段：

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

请求示例：

```json
{
  "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"
    }
  }
]
```

cURL 请求示例：

```bash
curl -X "POST" "https://api.cnb.cool/cnb/feedback/-/knowledge/base/query" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${token}" \
  -d '{
    "query": "云原生开发配置自定义按钮"
}'
```

拿到响应结果后，即可结合 `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 response = await fetch(`https://api.cnb.cool/${REPO_SLUG}/-/knowledge/base/query`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${CNB_TOKEN}`
    },
    body: JSON.stringify({ query: question })
  });
  
  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 角色
* 定制知识库按钮样式
* 设置默认仓库和默认角色

### 引入其他仓库配置

如果当前项目依赖其他仓库的文档，可以在知识库对话中引入其他仓库的知识库内容，以实现跨仓库检索。

具体配置方法请参考 [UI定制配置文件](../repo/settings.md) 中的 `npc.imports.list` 部分。

### 定义 AI 角色系统

你可以创建不同的 AI 角色，让它们以不同身份和风格回答问题。例如：

* **资浅工程师**：用简单易懂的方式解释概念
* **资中工程师**：提供专业的技术解答
* **资深工程师**：解决复杂技术问题，并提供架构设计和深度见解

具体配置方法请参考 [UI定制配置文件](../repo/settings.md) 中的 `npc.roles` 部分。

### 定制知识库按钮样式

你可以定制知识库入口按钮的名称、描述和悬浮效果图片，增强视觉体验和交互趣味。

具体配置方法请参考 [UI定制配置文件](../repo/settings.md) 中的 `npc.button` 部分。

### 设置默认仓库和默认角色选项

你可以为知识库弹窗预设默认选中的仓库和默认使用的 AI 角色，从而减少每次打开时的重复选择。

具体配置方法请参考 [UI定制配置文件](../repo/settings.md) 中的 `npc.defaultRepo` 和 `npc.defaultRole` 部分。

### 评论中 @AI 角色

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

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

更多详细信息，请参考 [NPC 事件](../build/trigger-rule.md#npc-事件)。