1948 字约 6 分钟
通过代码仓库可以快速创建企业或个人知识库,通过将文档上传到代码仓库,并配置知识库相关流水线, 可以自动将文档内容经过大模型处理后上传到知识库,供页面问答和 Open API 等场景调用, 可用于快速构建 RAG(Retrieval-Augmented Generation)应用。
知识准备
了解构建 RAG 应用流程
下图展示通过 CNB 的知识库插件 2 步构建 RAG 应用。

1. 使用知识库插件将仓库的文档导入到知识库
使用 CNB 知识库插件将仓库的文档导入到 CNB 的知识库中, 插件在云原生构建中运行, 会自动处理文档切片、分词、向量化等操作。 知识库构建完成后,可以被下游的 LLM 应用使用。
2. 调用 CNB Open API 检索,开发 LLM 应用
知识库构建完成后,使用 CNB 的 Open API 进行召回,并结合 LLM 模型生成回答。
常见的 RAG 应用运行流程如下:
1.用户提问
2.理解用户问题后,使用 Query 调用知识库检索。如上文所述,使用 CNB 的 Open API 进行检索,获取相关文档片段
3.拿到从 CNB 知识库检索的结果后,构建拼接 Prompt 问题 + 知识上下文,例如拼接后 prompt 一般会这样:
用户提问:{用户问题}
知识库:
{从知识库检索到的内容}
请根据以上知识库,回答用户的问题。4.将拼接后的 prompt 发送给 LLM 模型,生成回答,返回给用户
具体使用方法
步骤 1:配置流水线使用知识库插件
插件镜像名字:cnbcool/knowledge-base
在代码仓库的 .cnb.yml 中配置流水线,使用知识库插件。 如下图配置,当仓库的 main 分支有代码提交时,会触发流水线, 自动使用知识库插件对 Markdown 文件进行切片、分词、向量化等处理,并将处理后的内容上传到 CNB 的知识库中。
main:
push:
- stages:
- name: build knowledge base
image: cnbcool/knowledge-base
settings:
include:
- docs/*.md
- docs/*.txt部分插件参数说明如下,如果需要了解更多参数,请参考 cnbcool/knowledge-base 插件文档。
include:指定需要包含的文件,使用 glob 模式匹配,默认为*包含所有文件,支持数组或逗号分隔exclude:指定需要排除的文件,使用 glob 模式匹配,默认不排除任何文件,支持数组或逗号分隔chunk_size:指定文本分块大小,默认为 1500chunk_overlap:指定相邻两个分块之间的重叠token数量,默认为 0embedding_model:嵌入模型,默认为hunyuan,目前仅支持hunyuan
亦可在云原生开发使用如下命令,注意需要开启 Docker-in-Docker (Docker) 服务, 默认开发环境已经开启,自定义开发环境可以参考service-docker。
docker run --rm \
-v "$(pwd):$(pwd)" \
-w "$(pwd)" \
-e CNB_TOKEN=$CNB_TOKEN \
-e CNB_REPO_SLUG_LOWERCASE=$CNB_REPO_SLUG_LOWERCASE \
-e PLUGIN_INCLUDE="docs/*.md,docs/*.txt,docs/*.pdf" \
cnbcool/knowledge-base步骤 2:使用知识库
知识库构建完成后,可以通过 Open API 对该仓库所属知识库进行查询检索,召回后的内容可以结合 LLM 模型生成回答。
开始之前,请阅读:CNB Open API 使用教程, 访问令牌需要权限:repo-code:r(仓库读权限)
注意: {slug} 应替换为仓库 slug,例如 CNB 官方文档知识库的仓库地址为 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,匹配相关性分数阈值。
示例
{
"query": "云原生开发配置自定义按钮"
}响应内容
响应为 JSON 格式,包含一个结果数组,每个结果包含以下字段:
score:Number,匹配相关性分数,范围 0-1,值越高表示匹配度越高。chunk:String,匹配的知识库内容文本。metadata:Object,内容元数据。
metadata 字段详情
hash:String内容的唯一哈希值。name:String,文档名称。path:String,文档路径。position:Number,内容在原文档中的位置。score:Number,匹配相关性分数,值越高表示匹配度越高。type:String,内容类型,如code、issue。url:String,内容 URL。
响应示例
[
{
"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 请求示例
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 应用示例代码如下:
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定制配置文件 对知识库进行个性化定制,包括引入其他仓库配置、角色扮演、定制知识库按钮样式等。
引入其他仓库配置
在知识库对话中引用其他仓库的知识库内容,实现跨仓库的知识检索。例如当项目依赖其他仓库的文档时,可将其知识库一并引入。
具体配置方法请参考 UI定制配置文件 中的 knowledgeBase.imports.list 部分。
定义AI角色系统
创建不同的AI角色,每个角色具有特定的身份和回答风格。例如:
- 资浅工程师:用简单易懂的方式解释概念
- 资中工程师:提供专业的技术解答
- 资深工程师:解决复杂技术问题,提供架构设计和深度见解
具体配置方法请参考 UI定制配置文件 中的 knowledgeBase.roles 部分。
定制知识库按钮样式
定制知识库入口按钮的名称、描述和悬浮效果图片,增强视觉体验,更多趣味。
具体配置方法请参考 UI定制配置文件 中的 knowledgeBase.button 部分。
设置默认仓库和默认角色选项
配置知识库弹窗的默认选中仓库和默认使用的AI角色,以提升用户体验,减少每次操作的选择步骤。
具体配置方法请参考 UI定制配置文件 中的 knowledgeBase.defaultRepo 和 knowledgeBase.defaultRole 部分。