LangChain ↗ 是用于构建大语言模型应用的框架。langchain-cloudflare ↗ 包提供 CloudflareAISearchRetriever,这是由 AI Search 支持的标准 LangChain retriever。
retriever 仅负责搜索。要创建实例并上传内容,请将其与 Cloudflare Python SDK ↗ 配合使用。本指南使用 Python SDK 创建 AI Search 实例、索引文件,并将 LangChain retriever 用作搜索工具。新实例默认使用混合搜索。
要创建令牌,请按照 创建 API 令牌 操作,并添加这两项权限。Edit 用于预配实例并上传文件;Run 用于执行搜索。
创建项目目录和虚拟环境,以隔离依赖项。
mkdir ai-search-langchain && cd ai-search-langchain
python3 -m venv .venv
source .venv/bin/activate在 Windows 上,改用 .venv\Scripts\activate 激活虚拟环境。
安装这两个软件包:
pip install -U langchain-cloudflare cloudflarecloudflare SDK 用于创建实例并上传文件。langchain-cloudflare 包提供 retriever 以及 RAG 和智能体工具辅助函数。安装 langchain-cloudflare 也会安装 langchain-core,因此无需单独安装 langchain。
导出你的账户 ID 和 API 令牌。Cloudflare SDK 会自动读取它们。
export CLOUDFLARE_ACCOUNT_ID="<ACCOUNT_ID>"
export CLOUDFLARE_API_TOKEN="<API_TOKEN>"创建名为 main.py 的文件。新实例默认使用 混合搜索。由于未连接数据源,该实例使用 内置存储。
创建已存在的实例会失败,因此代码会先检查,仅在缺失时创建。
import os
from cloudflare import Cloudflare, NotFoundError
ACCOUNT_ID = os.environ["CLOUDFLARE_ACCOUNT_ID"]
API_TOKEN = os.environ["CLOUDFLARE_API_TOKEN"]
NAMESPACE = "default"
INSTANCE_NAME = "knowledge-base"
# The SDK authenticates with this token; the account ID is passed on each call.
client = Cloudflare(api_token=API_TOKEN)
# create() fails if the instance already exists, so check for it with read()
# first and only create it when read() raises NotFoundError.
try:
client.aisearch.namespaces.instances.read(
INSTANCE_NAME, account_id=ACCOUNT_ID, name=NAMESPACE
)
print(f"Instance '{INSTANCE_NAME}' already exists.")
except NotFoundError:
client.aisearch.namespaces.instances.create(
name=NAMESPACE,
account_id=ACCOUNT_ID,
id=INSTANCE_NAME,
)
print(f"Created instance '{INSTANCE_NAME}'.")create() 的第一个位置参数是 namespace 名称。
将以下内容添加到 main.py,以上传文档到内置存储。在 file 参数中将 wait_for_completion 设为 True 会等待文件完成索引后再返回。
item = client.aisearch.namespaces.instances.items.upload(
id=INSTANCE_NAME,
account_id=ACCOUNT_ID,
name=NAMESPACE,
file={
# (filename, file bytes, content type)
"file": (
"workers-ai.md",
b"To configure Workers AI, add an [ai] binding and call env.AI.run().",
"text/markdown",
),
# Block until indexing finishes so the file is searchable right away.
"wait_for_completion": True,
},
)
print(f"Uploaded '{item.key}' (status: {item.status}).")如果索引仍在完成中,item.status 可能为 running;文件会在后台继续索引,并很快变为可搜索。
有三种从 LangChain 使用实例的方式。选择适合你应用的一种:
- 直接搜索 返回匹配的文档。
- 将 AI Search 用作智能体工具 让智能体能够搜索你的内容。
- 构建 RAG 链 根据检索到的文档生成答案。
这三种方式都使用相同的 CloudflareAISearchRetriever,由第一种方式创建。
将 CloudflareAISearchRetriever 指向该实例。将 retrieval_type 设为 hybrid,以使用已启用的向量索引和关键词索引。
from langchain_cloudflare import CloudflareAISearchRetriever
retriever = CloudflareAISearchRetriever(
account_id=ACCOUNT_ID,
api_token=API_TOKEN,
instance_name=INSTANCE_NAME,
namespace=NAMESPACE,
retrieval_type="hybrid", # query both the vector and keyword indexes
k=5, # maximum number of results to return (capped at 50)
)
# invoke() runs a search and returns standard LangChain Documents.
docs = retriever.invoke("How do I configure Workers AI?")
for doc in docs:
# Each document carries its relevance score and source filename in metadata.
print(doc.metadata["score"], doc.metadata["filename"])
print(doc.page_content)k 参数设置最大结果数,映射到 max_num_results,上限为 50。
用 create_retriever_tool 包装 retriever,让智能体能够搜索你的内容。这是从 LangChain 智能体使用 AI Search 的推荐方式。
from langchain_core.tools import create_retriever_tool
# create_retriever_tool wraps the retriever as a standard LangChain tool. The
# name and description are what the agent's model sees when deciding to call it.
search_tool = create_retriever_tool(
retriever,
name="cloudflare_ai_search",
description="Search the knowledge base for relevant passages.",
)
print(search_tool.invoke({"query": "How do I configure Workers AI?"}))search_tool 是标准的 LangChain 工具。可以将其与其他工具一起传给任何 LangChain 或 LangGraph 智能体。
要根据检索到的内容回答问题,请将 retriever 与模型组合。本示例使用同一软件包中包含的 ChatCloudflareWorkersAI。以与 retriever 相同的方式传入账户 ID 和令牌。
由于此选项会调用 Workers AI 生成答案,此处传入的令牌还需要 Workers AI 权限。将其添加到你已创建的令牌中,或传入单独的令牌。
from langchain_cloudflare import ChatCloudflareWorkersAI
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
llm = ChatCloudflareWorkersAI(
account_id=ACCOUNT_ID,
api_token=API_TOKEN,
model="@cf/zai-org/glm-5.2",
)
prompt = ChatPromptTemplate.from_template(
"Answer the question using only the context below.\n\n"
"Context:\n{context}\n\n"
"Question: {question}"
)
# Join the retrieved documents into a single context string for the prompt.
def format_docs(docs):
return "\n\n".join(doc.page_content for doc in docs)
# LCEL chain: retrieve context and pass the question through, fill the prompt,
# call the model, then parse the response down to a plain string.
chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
print(chain.invoke("How do I configure Workers AI?"))在 Python Worker 中,传入 Worker 绑定而不是 REST 凭据。绑定路径是异步的,因此请使用 ainvoke。
from workers import WorkerEntrypoint, Response
from langchain_cloudflare import CloudflareAISearchRetriever
class Default(WorkerEntrypoint):
async def fetch(self, request):
# Pass a Worker binding instead of REST credentials.
retriever = CloudflareAISearchRetriever(binding=self.env.MY_SEARCH)
# The binding path is asynchronous, so use ainvoke.
docs = await retriever.ainvoke("How do I configure Workers AI?")
return Response.json({"matches": [doc.page_content for doc in docs]})self.env.MY_SEARCH 是专用的 ai_search 绑定,而不是 Workers AI 绑定(self.env.AI)。对于 namespace 绑定,请传入 self.env.<NAMESPACE>.get("my-instance")。