CreateKnowledgeBase Create a knowledge base - Tablestore

Use the CreateKnowledgeBase API to create a new knowledge base in the current AgentStorage instance. After creation, the system automatically creates a Document table, a Chunk table, and an index table in the instance to store documents, chunks, and index data.

Prerequisites

An AgentStorage instance has been created and is in the normal state, and the instance endpoint and instance name have been obtained.
An API Key has been created.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Name of the knowledge base (required). Must start with a letter and contain only letters, digits, and underscores. Length: 1-64 characters. Must be unique.
`description`	string	Description of the knowledge base. Maximum 4 KB.
`subspace`	boolean	Whether to enable subspaces. Defaults to `false`. When enabled, all document operations and retrieval must specify the `subspace` field. Cannot be modified after creation.
`tags`	list<string>	List of tags. Total length must not exceed 4 KB.
`metadata`	list<object>	Metadata field definitions. See the description below.
`embeddingConfiguration`	object	Embedding configuration. Cannot be modified after creation. If not specified, defaults to Bailian `text-embedding-v4` (1024 dimensions).
`retrievalConfiguration`	object	Default retrieval configuration. Used when `Retrieve` is called without specifying a configuration. Can be modified via `UpdateKnowledgeBase` after creation.

### metadata field definitions

Each element contains name (field name) and type (field type). Metadata field definitions cannot be added or deleted after the knowledge base is created; plan all fields needed for filtering before creation. Subsequent metadata values provided when importing or updating documents must conform to this definition.

Definition item	Description
Supported types	`string`, `long`, `double`, `boolean`, `date`, `string_list`, `long_list`, `double_list`, `boolean_list`, `date_list`
Field name	Maximum 128 UTF-8 bytes, must not contain `.`
Number of fields	Up to 200
Reserved fields	`_uid`, `_id`, `_type`, `_all`, `_parent`, `_routing`, `_index`, `_size`, `_timestamp`, `_ttl`, `_score`

### embeddingConfiguration

Parameter	Type	Description
`provider`	string	Model provider. Defaults to `bailian` (Bailian built-in); also supports `custom` (custom).
`model`	string	Model name. Defaults to `text-embedding-v4`; Bailian also supports `text-embedding-v3`.
`dimension`	int	Vector dimension. Default: 1024.
`apiKey`	string	Required only in `custom` mode.
`url`	string	Required only in `custom` mode. Must be registered with Tablestore in advance.

### retrievalConfiguration

Parameter	Type	Description
`searchType`	list<string>	Retrieval type. Defaults to `["DENSE_VECTOR", "FULL_TEXT"]`.
`denseVectorSearchConfiguration.numberOfResults`	int	Number of results returned by vector retrieval. Default: 20.
`fullTextSearchConfiguration.numberOfResults`	int	Number of results returned by full-text search. Default: 20.
`rerankingConfiguration.type`	string	Rerank type: `RRF`, `WEIGHT`, or `MODEL`. Default: `WEIGHT`.
`rerankingConfiguration.numberOfResults`	int	Number of results returned after reranking. Default: 20.
`weightConfiguration.denseVectorSearchWeight`	double	Vector retrieval weight ratio. Default: 0.7.
`weightConfiguration.fullTextSearchWeight`	double	Full-text search weight ratio. Default: 0.3.
`rrfConfiguration.denseVectorSearchWeight`	double	Vector retrieval weight in RRF mode. Default: 1.0.
`rrfConfiguration.fullTextSearchWeight`	double	Full-text search weight in RRF mode. Default: 1.0.
`rrfConfiguration.k`	int	RRF algorithm parameter. Default: 60. Must be greater than 0.
`modelConfiguration.provider`	string	Rerank model provider. Defaults to `bailian`. Currently only Bailian is supported.
`modelConfiguration.model`	string	Rerank model name. Defaults to `gte-rerank-v2` (defaults to `qwen3-rerank` in the Singapore region).

For complete retrieval configuration details, see Retrieve and sort.

Request example

When using API Key authentication, pass the instance name and API Key through the x-ots-instancename and x-ots-apikey request headers.

curl -X POST https://<endpoint>/CreateKnowledgeBase \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseName": "product_docs_kb",
    "description": "产品文档知识库",
    "subspace": true,
    "tags": ["产品", "文档"],
    "metadata": [
      {"name": "author", "type": "string"},
      {"name": "date", "type": "date"},
      {"name": "score", "type": "double"}
    ],
    "embeddingConfiguration": {
      "provider": "bailian",
      "model": "text-embedding-v4",
      "dimension": 1024
    },
    "retrievalConfiguration": {
      "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
      "denseVectorSearchConfiguration": {"numberOfResults": 10},
      "fullTextSearchConfiguration": {"numberOfResults": 10},
      "rerankingConfiguration": {
        "type": "RRF",
        "numberOfResults": 5,
        "rrfConfiguration": {"denseVectorSearchWeight": 0.6, "fullTextSearchWeight": 0.4, "k": 60}
      }
    }
  }'

Response

{"code": "SUCCESS", "data": {}, "message": "succeed"}