使用插件将仓库的文档导入到 CNB 的知识库中，以支持搜索或 LLM RAG 问答。

目前支持 Markdown, mdx, pdf, docx, txt 文件。文件类型仅根据后缀名判断。

通过上图，可以看到使用过程分为两步：

使用本知识库插件将仓库的文档导入到 CNB 的知识库中， 本插件在 CNB 云原生构建中运行， 会自动处理文档，并构建知识库， 知识库构建完成后，可以被下游的 LLM 应用使用。

知识库构建完成后，使用 CNB 的 Open API 进行召回，并结合 LLM 拼接模型生成回答。

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

1.用户提问

2.问题理解

3.调用知识库检索，如上文所述，使用 CNB 的 Open API 进行召回，获取相关文档

4.构建拼接 Prompt， 问题 + 知识上下文，例如拼接后 prompt 一般会这样：

用户：{用户问题}

知识库：
{知识库内容}

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

5.将拼接后的 prompt 发送给 LLM 模型，生成回答，返回给用户

cnbcool/knowledge-base

• include：指定需要包含的文件，使用 glob 模式匹配，默认为 * 包含所有文件，支持数组或逗号分隔
• exclude：指定需要排除的文件，使用 glob 模式匹配，默认不排除任何文件，支持数组或逗号分隔
• force_rebuild：是否删除知识库并重新构建。默认为 false。当设置为 true 时，删除并重新创建知识库
• chunk_size：指定文本分块大小，默认为 1500
• chunk_overlap：指定相邻两个分块之间的重叠token数量，默认为 0
• ignore_process_failures：是否忽略文档处理失败，默认为 false。当设置为 true 时，即使有文件处理失败也会更新知识库
• issue_sync_enabled：是否启用 Issue 同步功能，默认为 false。启用后会自动拉取仓库的 Issue 数据并加入知识库
• issue_state：仅同步指定状态的 Issue，默认包含全部 Issue，可选值为 open|closed
• issue_labels：仅同步指定标签的 Issue ，默认包含全部 Issue，支持数组或逗号分隔，
• embedding_model：嵌入模型，默认为 hunyuan，目前仅支持 hunyuan

注意： exclude的优先级高于include，被 exclude 的文件不会再被 include

main:
  push:
    - stages:
        - name: build knowledge base
          image: cnbcool/knowledge-base
          settings:
            include: 
              - docs/*.md
              - docs/*.txt

main:
  push:
    - stages:
        - name: build knowledge base
          image: cnbcool/knowledge-base
          settings:
            include:
              - docs/*.md
              - docs/*.txt            
            issue_sync_enabled: true
            issue_labels:
              - bug
              - feature
            issue_state: "open"
            issue_priority: "P0,P1"

此 API 用于查询知识库内容，根据提供的查询关键词返回相关信息。

开始之前，请阅读：CNB Open API 使用教程 访问令牌需要权限：repo-code:r（读取仓库代码）

• URL: https://api.cnb.cool/{slug}/-/knowledge/base/query
• 方法: POST
• 内容类型: application/json

注意: {slug} 应替换为仓库 slug，例如 CNB 官方文档知识库的仓库地址为 https://cnb.cool/cnb/docs， 则 {slug} 就是 cnb/docs

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

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

{
    "query": "云原生开发配置自定义按钮"
}

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

• score: Number, 匹配相关性分数，范围 0-1。
• chunk: String, 匹配的知识库内容文本。
• metadata: Object, 内容元数据。

• 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": "quick-start",
            "path": "vscode/quick-start.md",
            "position": 0,
            "score": 0.8671732
        }
    }
]

注意：{slug} 是运行知识库插件的仓库 slug，例如 CNB 官方文档知识库为 cnb/docs

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

1. 响应中的 chunk 字段包含了匹配到的知识库内容片段，为 Markdown 格式的文本。
2. score 值越高表示匹配度越高。
3. URL 中的 slug 是运行知识库插件的仓库 slug。