Knowledge Base

About 1397 wordsAbout 5 min

You can quickly create enterprise or personal knowledge bases through code repositories. By uploading documents to a code repository and configuring knowledge base-related pipelines, you can automatically process document content through large models and upload it to the knowledge base for use in scenarios such as page Q&A and Open API calls. This can be used to quickly build RAG (Retrieval-Augmented Generation) applications.

Prerequisites

Understanding the RAG Application Building Process

The following diagram shows the 2-step process of building a RAG application using CNB's knowledge base plugin.

Build RAG application in 2 steps using CNB knowledge base plugin

1. Use the knowledge base plugin to import repository documents to the knowledge base

Use the CNB knowledge base plugin to import repository documents into CNB's knowledge base. The plugin runs in cloud-native builds and automatically handles document slicing, tokenization, vectorization, and other operations. Once the knowledge base is built, it can be used by downstream LLM applications.

2. Call CNB Open API for retrieval and develop LLM applications

After the knowledge base is built, use CNB's Open API for retrieval and combine it with LLM models to generate answers.

The common RAG application workflow is as follows:

User asks a question
After understanding the user's question, use Query to call the knowledge base for retrieval. As mentioned above, use CNB's Open API for retrieval to get relevant document fragments
After getting the retrieval results from the CNB knowledge base, construct and concatenate the Prompt question + knowledge context. For example, the concatenated prompt generally looks like this:

User Question: {User Question}

Knowledge Base:
{Content retrieved from knowledge base}

Please answer the user's question based on the knowledge base above.

Send the concatenated prompt to the LLM model to generate an answer and return it to the user

Usage

Step 1: Configure pipeline to use the knowledge base plugin

Plugin image name: cnbcool/knowledge-base

Configure the pipeline in the code repository's .cnb.yml to use the knowledge base plugin. As shown in the configuration below, when there is a code commit to the repository's main branch, it triggers the pipeline to automatically use the knowledge base plugin to slice, tokenize, vectorize Markdown files and upload the processed content to CNB's knowledge base.

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

Some plugin parameters are described below. For more parameters, please refer to the cnbcool/knowledge-base plugin documentation.

include: Specifies the files to include, using glob pattern matching, defaults to * to include all files, supports arrays or comma-separated values
exclude: Specifies the files to exclude, using glob pattern matching, defaults to excluding no files, supports arrays or comma-separated values
chunk_size: Specifies the text chunk size, defaults to 1500
chunk_overlap: Specifies the number of overlapping tokens between adjacent chunks, defaults to 0
embedding_model: Embedding model, defaults to hunyuan, currently only supports hunyuan

You can also use the following command in cloud-native development. Note that you need to enable the Docker-in-Docker (Docker) service. The default development environment has it enabled. For custom development environments, please refer to 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

Step 2: Use the knowledge base

After the knowledge base is built, you can query and retrieve the knowledge base belonging to that repository through Open API. The retrieved content can be combined with LLM models to generate answers.

Before starting, please read: CNB Open API Tutorial, Access token requires permission: repo-code:r (repository read permission)

Note: {slug} should be replaced with the repository slug. For example, if the repository address of the CNB official documentation knowledge base is https://cnb.cool/cnb/feedback, then {slug} is cnb/feedback

Enabling Knowledge Base in AI Conversations

After the knowledge base is built, you can enable it in the AI conversation feature on the repository page, allowing AI to converse based on your repository's document content.

You can also personalize the knowledge base through .cnb/settings.yml UI customization configuration file, including importing configurations from other repositories, role-playing, customizing knowledge base button styles, etc.

Importing configurations from other repositories

Reference knowledge base content from other repositories in knowledge base conversations to achieve cross-repository knowledge retrieval. For example, when your project depends on documentation from other repositories, you can import their knowledge bases together.

For specific configuration methods, please refer to the knowledgeBase.imports.list section in the UI customization configuration file.

Defining AI role system

Create different AI roles, each with a specific identity and response style. For example:

Junior Engineer: Explain concepts in simple and understandable terms
Mid-level Engineer: Provide professional technical answers
Senior Engineer: Solve complex technical problems, provide architectural design and deep insights

For specific configuration methods, please refer to the knowledgeBase.roles section in the UI customization configuration file.

URL: https://api.cnb.cool/{slug}/-/knowledge/base/query
Method: POST
Content Type: application/json

Request Parameters

The request body should be in JSON format and contain the following fields:

query: String, required, the keyword or question to query.
top_k: Number, default 5, the maximum number of results to return.
score_threshold: Number, default 0, the matching relevance score threshold.

Example

{
  "query": "Configure custom buttons in cloud-native development"
}

Response Content

The response is in JSON format and contains a result array. Each result contains the following fields:

score: Number, matching relevance score, range 0-1, higher value indicates higher matching degree.
chunk: String, the matched knowledge base content text.
metadata: Object, content metadata.

metadata field details

hash: String, the unique hash value of the content.
name: String, document name.
path: String, document path.
position: Number, the position of the content in the original document.
score: Number, matching relevance score, higher value indicates higher matching degree.
type: String, content type, such as code, issue.
url: String, content URL.

Response example

[
  {
    "score": 0.8671732,
    "chunk": "This cloud-native remote development solution is based on 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 request example

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": "Configure custom buttons in cloud-native development"
}'

The retrieved response content can be combined with LLM models to generate answers.

RAG Mini Application Example

For example, here is a simple RAG application example code implemented in JavaScript:

import OpenAI from 'openai';

// Configuration
const CNB_TOKEN = 'your-cnb-token'; // Replace with your CNB access token, requires permission: `repo-code:r`
const OPENAI_API_KEY = 'your-openai-api-key'; // Replace with your OpenAI API key
const OPENAI_BASE_URL = 'https://api.openai.com/v1'; // Or your proxy address
const REPO_SLUG = 'cnb/feedback'; // Replace with your repository slug

// Initialize OpenAI client
const openai = new OpenAI({
  apiKey: OPENAI_API_KEY,
  baseURL: OPENAI_BASE_URL
});

async function simpleRAG(question) {
  // 1. Call CNB knowledge base for retrieval
  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. Extract knowledge content (here we assume taking all results)
  const knowledge = knowledgeResults
    .map(item => item.chunk)
    .join('\n\n');

  // 3. Call OpenAI to generate answer
  const completion = await openai.chat.completions.create({
    model: "gpt-4.1-2025-04-14",
    messages: [
      {
        role: "user",
        content: `Question: ${question}\n\nKnowledge Base: ${knowledge}\n\nPlease answer the question based on the knowledge base.`,
      },
    ],
  });

  return completion.choices[0].message.content;
}

// Usage example
const answer = await simpleRAG("How to develop a plugin?");
// Output answer combined with knowledge base
console.log(answer);