Python SDK

このガイドでは、Cloudflare Python SDK ↗ を使い、Python アプリケーションから AI Search インスタンスの作成、コンテンツのアップロード、クエリまでを進めます。

• Python ↗ 3.8 以降。
• アカウント ID。

このガイドは default 名前空間 を使います。この名前空間は、すべてのアカウントに自動で存在します。独自の名前空間にインスタンスをまとめる場合は、client.aisearch.namespaces.create() で作成します。

AI Search:Edit と AI Search:Run の権限を持つ API トークンが必要です。

1. Cloudflare ダッシュボードで、My Profile > API Tokens を開きます。

   API Tokens を開く ↗

2. Create Token を選択します。

3. Create Custom Token を選択します。

4. Token name を入力します。例: AI Search Python。

5. Permissions で、次の 2 つの権限を追加します。

   • Account > AI Search:Edit
   • Account > AI Search:Run

6. Continue to summary を選択し、Create Token を選択します。

7. トークン値をコピーして保存します。これが API_TOKEN です。

依存関係を分離するため、プロジェクトディレクトリと仮想環境を作成します。

mkdir ai-search-python && cd ai-search-python
python3 -m venv .venv
source .venv/bin/activate

Windows では、仮想環境の有効化に .venv\Scripts\activate を使います。

公式の cloudflare パッケージをインストールします。

pip install cloudflare

アカウント ID と API トークンを環境変数としてエクスポートします。

export CLOUDFLARE_ACCOUNT_ID="<ACCOUNT_ID>"
export CLOUDFLARE_API_TOKEN="<API_TOKEN>"

quickstart.py という名前のファイルを作成します。次のコードはクライアントを用意し、default 名前空間に my-instance というインスタンスを作成します。データソースを指定していないため、インスタンスは 組み込みストレージ を使い、ファイルを直接アップロードできます。

import os

from cloudflare import Cloudflare

client = Cloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"])
account_id = os.environ["CLOUDFLARE_ACCOUNT_ID"]

instance = client.aisearch.namespaces.instances.create(
    name="default",
    account_id=account_id,
    id="my-instance",
)

print(f"Created instance: {instance.id}")

次を quickstart.py に追加し、ドキュメントをアップロードします。wait_for_completion を True にすると、インデックス完了を待ってから戻るため、ファイルはすぐに検索できます。インデックスがまだ終わっていない場合、item.status は running になることがあります。ファイルはバックグラウンドでインデックスを続け、まもなく検索可能になります。

item = client.aisearch.namespaces.instances.items.upload(
    id="my-instance",
    account_id=account_id,
    name="default",
    file={
        "file": (
            "getting-started.md",
            b"AI Search indexes uploaded content for retrieval.",
            "text/markdown",
        ),
        "wait_for_completion": True,
    },
)

print(f"Uploaded item status: {item.status}")

次を quickstart.py に追加し、インデックス済みコンテンツに対してクエリを実行します。

results = client.aisearch.namespaces.instances.search(
    id="my-instance",
    account_id=account_id,
    name="default",
    query="How does AI Search handle uploaded content?",
)

if results.chunks:
    print(results.chunks[0].text)
else:
    print("No results yet — your content may still be indexing. Try again in a moment.")

スクリプトを実行します。

python quickstart.py

検索結果が空の場合、コンテンツのインデックスがまだ終わっていない可能性があります。少し待ってから、もう一度検索してください。