本指南将引导你使用 Cloudflare Python SDK ↗ 创建 AI Search 实例、上传内容，并从 Python 应用进行查询。
本指南使用每个账户自动存在的 default namespace。若要将实例分组到自己的 namespace，请使用 client.aisearch.namespaces.create() 创建一个。
你需要具有 AI Search:Edit 和 AI Search:Run 权限的 API token。
-
在 Cloudflare 仪表板中，前往 My Profile（我的个人资料） > API Tokens（API 令牌）。
Go to API Tokens ↗ -
选择 Create Token（创建令牌）。
-
选择 Create Custom Token（创建自定义令牌）。
-
输入 Token name（令牌名称），例如
AI Search Python。 -
在 Permissions（权限） 下，添加两项权限：
- Account > AI Search:Edit
- Account > AI Search:Run
-
选择 Continue to summary（继续到摘要），然后选择 Create Token（创建令牌）。
-
复制并保存 token 值。这就是你的
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 token 导出为环境变量。
export CLOUDFLARE_ACCOUNT_ID="<ACCOUNT_ID>"
export CLOUDFLARE_API_TOKEN="<API_TOKEN>"创建名为 quickstart.py 的文件。以下代码会初始化客户端，并在 default namespace 中创建名为 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如果搜索没有返回结果，内容可能仍在索引中。稍等片刻后再次运行搜索。