ナレッジベース管理 (作成、更新、詳細の照会、一覧取得、削除) - Tablestore

以下の API を使用して、ナレッジベースの作成、更新、詳細の照会、一覧取得、削除を行います。

ナレッジベースの作成

create_knowledge_base を呼び出してナレッジベースを作成します。システムは対応するドキュメントテーブルとチャンクテーブルを Tablestore に自動的に作成します。

リクエストパラメーター

パラメーター	タイプ	説明
`knowledgeBaseName`	string	(必須) ナレッジベースの一意の名前。長さは 1〜64 文字で、先頭は英字である必要があります。英字、数字、アンダースコア (_) のみ使用できます。
`description`	string	ナレッジベースの説明。最大サイズは 4 KB です。
`subspace`	boolean	サブスペースマルチテナンシーを有効にするかどうかを指定します。詳細については、「サブスペースマルチテナンシー」をご参照ください。デフォルト値は `false` です。有効にした場合、すべてのドキュメント操作と取得リクエストで `subspace` フィールドを指定する必要があります。このパラメーターは作成後に変更できません。
`tags`	list<string>	タグのリスト。合計サイズは 4 KB を超えることはできません。
`metadata`	list<object>	メタデータフィールドを定義します。詳細については、以下のセクションをご参照ください。
`embeddingConfiguration`	object	埋め込み設定。指定しない場合、システムはデフォルトで Model Studio の `text-embedding-v4` モデル (1024 ディメンション) を使用します。このパラメーターは作成後に変更できません。
`retrievalConfiguration`	object	デフォルトの取得設定。`Retrieve` API を呼び出す際、デフォルトでこの設定が使用されます。この設定は、後で `update_knowledge_base` を呼び出して変更できます。

メタデータフィールドの定義

各要素には、name (フィールド名) と type (フィールドタイプ) が含まれます。

項目	説明
サポートされているタイプ	`string`、`long`、`double`、`boolean`、`date`、`string_list`、`long_list`、`double_list`、`boolean_list`、および `date_list` 説明 `date` 型は、`yyyy-MM-dd`、`yyyy-MM-dd HH:mm:ss`、`yyyy-MM-dd HH:mm:ss.SSS`、`yyyyMMdd HHmmss`、および `yyyy-MM-dd'T'HH:mm:ss` のフォーマットに対応しています。
フィールド名	最大長は 128 文字です。名前にピリオド (`.`) を含めることはできません。上限の引き上げをリクエストするには、チケットを送信するか、Tablestore サポートグループ (ID: 36165029092) を通じてテクニカルサポートにお問い合わせください。
フィールド数	最大 200 フィールド。上限の引き上げをリクエストするには、チケットを送信するか、Tablestore サポートグループ (ID: 36165029092) を通じてテクニカルサポートにお問い合わせください。
予約済みフィールド	`_uid`、`_id`、`_type`、`_all`、`_parent`、`_routing`、`_index`、`_size`、`_timestamp`、`_ttl`、および `_score`。

重要

ナレッジベースの作成後は、メタデータフィールドの定義を追加または削除することはできません。作成前に、結果のフィルタリングに使用する可能性のあるすべてのディメンションを特定し、定義してください。

埋め込み設定

パラメーター	タイプ	説明
`provider`	string	モデルプロバイダー。デフォルト値は、組み込みの Model Studio モデルに対応する `bailian` です。`custom` にも対応しています。
`model`	string	モデル名。デフォルト値は `text-embedding-v4` です。Model Studio は `text-embedding-v3` もサポートしています。
`dimension`	int	ベクトルのディメンション。デフォルト値は 1024 です。
`apiKey`	string	`provider` が `custom` に設定されている場合にのみ必須です。
`url`	string	`provider` が `custom` に設定されている場合にのみ必須です。事前に Tablestore に連絡して URL を登録する必要があります。

取得設定

パラメーター	タイプ	説明
`searchType`	list<string>	デフォルトの取得タイプは `["DENSE_VECTOR", "FULL_TEXT"]` です。
`denseVectorSearchConfiguration.numberOfResults`	int	ベクトル検索から返す結果の数。デフォルト値は 20 です。
`fullTextSearchConfiguration.numberOfResults`	int	全文検索から返す結果の数。デフォルト値は 20 です。
`rerankingConfiguration.type`	string	再ランキングのタイプ： `RRF`、`WEIGHT`、または `MODEL`。デフォルト値は `WEIGHT` です。
`rerankingConfiguration.numberOfResults`	int	再ランキング後に返す結果の数。デフォルト値は 20 です。
`weightConfiguration.denseVectorSearchWeight`	double	ベクトル検索結果の重み。デフォルト値は 0.7 です。
`weightConfiguration.fullTextSearchWeight`	double	全文検索結果の重み。デフォルト値は 0.3 です。
`rrfConfiguration.denseVectorSearchWeight`	double	RRF モードでのベクトル検索の重み。デフォルト値は 1.0 です。
`rrfConfiguration.fullTextSearchWeight`	double	RRF モードでの全文検索の重み。デフォルト値は 1.0 です。
`rrfConfiguration.k`	int	RRF アルゴリズムの `k` パラメーター。デフォルト値は 60 です。値は 0 より大きい必要があります。
`modelConfiguration.provider`	string	再ランキングモデルのプロバイダー。デフォルト値は、Model Studio に対応する `bailian` です。現在サポートされている唯一のプロバイダーです。
`modelConfiguration.model`	string	再ランキングモデルの名前。デフォルト値は `gte-rerank-v2` です。アジアパシフィック南東 1 (シンガポール) リージョンでは、デフォルトは `qwen3-rerank` です。

取得設定の詳細については、「取得と再ランキング」をご参照ください。

コード例

以下の例は、ナレッジベースを作成する方法を示しています。

最小限の例

デフォルト設定でナレッジベースを作成します。デフォルトでは、システムは埋め込みに Model Studio の text-embedding-v4 モデル (1024 ディメンション)、取得にハイブリッド検索 (ベクトル検索と全文検索の組み合わせ)、再ランキングに重み付けフュージョン (ベクトル検索： 0.7、全文検索： 0.3) を使用します。

client.create_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

完全な例

カスタムの埋め込みモデル、取得戦略、メタデータフィールドを使用してナレッジベースを作成します：

client.create_knowledge_base({
    "knowledgeBaseName": "product_docs_kb",
    "description": "Product documentation knowledge base",
    "subspace": True,
    "tags": ["Product", "Documentation"],
    "metadata": [
        {"name": "author", "type": "string"},
        {"name": "category", "type": "string"},
        {"name": "publish_date", "type": "date"}
    ],
    "embeddingConfiguration": {
        "provider": "bailian",
        "model": "text-embedding-v4",
        "dimension": 1024
    },
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
        "denseVectorSearchConfiguration": {"numberOfResults": 10},
        "fullTextSearchConfiguration": {"numberOfResults": 10},
        "rerankingConfiguration": {
            "type": "WEIGHT",
            "numberOfResults": 5,
            "weightConfiguration": {
                "denseVectorSearchWeight": 0.7,
                "fullTextSearchWeight": 0.3
            }
        }
    }
})

レスポンス

成功レスポンス：

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

エラーレスポンスの例：

{
  "code": "INVALID_PARAMETER",
  "message": "Unknown field type: strings, supported types: string, long, double, boolean, date, string_list, long_list, double_list, boolean_list, date_list"
}

注意事項

embeddingConfiguration は作成後に変更できません。異なる埋め込みモデルを使用するには、ナレッジベースを削除して再作成する必要があります。
作成後に metadata フィールドの定義を追加または削除することはできません。
作成後に subspace 設定を変更することはできません。
metadata フィールド名にピリオド (.) を含めたり、予約済みフィールドにしたりすることはできません。フィールドタイプのスペルを間違えるとエラーが発生します。

ナレッジベースの更新

update_knowledge_base を呼び出して、ナレッジベースの説明、タグ、または取得設定を更新します。

リクエストパラメーター

パラメーター	タイプ	説明
`knowledgeBaseName`	string	ナレッジベースの名前 (必須)。
`description`	string	ナレッジベースの新しい説明。最大サイズは 4 KB です。
`tags`	list<string>	新しいタグのリスト。
`retrievalConfiguration`	object	新しいデフォルトの取得設定。

説明

description、tags、または retrievalConfiguration のうち、少なくとも 1 つのパラメーターを指定する必要があります。指定しない場合、エラーが返されます。

コード例

client.update_knowledge_base({
    "knowledgeBaseName": "product_docs_kb",
    "description": "Updated description",
    "tags": ["Live"],
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
        "rerankingConfiguration": {
            "type": "RRF",
            "numberOfResults": 10,
            "rrfConfiguration": {
                "denseVectorSearchWeight": 0.7,
                "fullTextSearchWeight": 0.3,
                "k": 60
            }
        }
    }
})

注意事項

retrievalConfiguration を更新すると、その設定が後続のすべての Retrieve リクエストの新しいデフォルトになります。この変更は、独自の設定を指定する Retrieve リクエストには影響しません。
この API で embeddingConfiguration または metadata を変更することはできません。

ナレッジベースの詳細の照会

describe_knowledge_base を呼び出して、ナレッジベースの完全な設定を取得します。

リクエストパラメーター

パラメーター	タイプ	説明
`knowledgeBaseName`	string	ナレッジベースの名前 (必須)。

コード例

resp = client.describe_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

data = resp["data"]
print(f"Name: {data['knowledgeBaseName']}")
print(f"Embedding: {data['embeddingConfiguration']}")
print(f"Retrieval Configuration: {data['retrievalConfiguration']}")

レスポンス

レスポンスフィールド

フィールド	タイプ	説明
`knowledgeBaseName`	string	ナレッジベースの名前。
`description`	string	ナレッジベースの説明。
`tags`	list<string>	タグのリスト。
`subspace`	boolean	サブスペースが有効かどうかを示します。
`createdAt`	int	作成タイムスタンプ (ミリ秒)。
`updatedAt`	int	最終更新タイムスタンプ (ミリ秒)。
`metadata`	list<object>	メタデータフィールドの定義。
`embeddingConfiguration`	object	埋め込み設定。
`retrievalConfiguration`	object	取得設定。

レスポンスの例

{
  "code": "SUCCESS",
  "data": {
    "knowledgeBaseName": "product_docs_kb",
    "description": "Product documentation knowledge base",
    "tags": ["Product", "Documentation"],
    "subspace": true,
    "metadata": [{"name": "author", "type": "string"}],
    "createdAt": 1774494642525,
    "updatedAt": 1774494642525,
    "embeddingConfiguration": {
      "provider": "bailian",
      "model": "text-embedding-v4",
      "dimension": 1024
    },
    "retrievalConfiguration": {
      "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
      "denseVectorSearchConfiguration": {"numberOfResults": 20},
      "fullTextSearchConfiguration": {"numberOfResults": 20},
      "rerankingConfiguration": {
        "type": "WEIGHT",
        "numberOfResults": 20,
        "weightConfiguration": {
          "denseVectorSearchWeight": 0.7,
          "fullTextSearchWeight": 0.3
        }
      }
    }
  },
  "message": "succeed"
}

ナレッジベースの一覧取得

list_knowledge_base を呼び出して、現在のプロジェクト内のすべてのナレッジベースのページ分割されたリストを取得します。

リクエストパラメーター

パラメーター	タイプ	説明
`maxResults`	int	返す結果の数。デフォルト値は 10、最大値は 100 です。
`nextToken`	string	結果の次のページを取得するためのページネーショントークン。最初のリクエストではこれを省略します。

コード例

# 最初のページを取得
resp = client.list_knowledge_base({"maxResults": 10})

for kb in resp["data"]["knowledgeBases"]:
    print(f"{kb['knowledgeBaseName']} - {kb.get('description', '')}")

# 次のページを取得
next_token = resp["data"].get("nextToken")
if next_token:
    resp = client.list_knowledge_base({
        "maxResults": 10,
        "nextToken": next_token
    })

レスポンス

フィールド	タイプ	説明
`knowledgeBases`	list<object>	ナレッジベースのリスト。各項目には `knowledgeBaseName`、`description`、`subspace`、`tags`、`createdAt`、および `updatedAt` が含まれます。
`nextToken`	string	ページネーショントークン。空または null の値は、これ以上結果がないことを示します。

注意事項

maxResults の最大値は 100 です。100 を超える値を指定すると、INVALID_PARAMETER エラーが返されます。

ナレッジベースの削除

delete_knowledge_base を呼び出して、ナレッジベースを削除します。

重要

この操作は元に戻せません。ナレッジベースを削除すると、関連するすべてのドキュメントデータとチャンクデータも削除されます。

リクエストパラメーター

パラメーター	タイプ	説明
`knowledgeBaseName`	string	ナレッジベースの名前 (必須)。

コード例

client.delete_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

レスポンス

成功レスポンス：

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

エラーレスポンスの例：

{"code": "NOT_FOUND", "message": "KnowledgeBaseName:[product_docs_kb] not found"}