跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

LangChain

最后更新 查看 MarkdownAgent 设置

LangChain ↗ 是用于构建大语言模型应用的框架。langchain-cloudflare ↗ 包提供 CloudflareAISearchRetriever,这是由 AI Search 支持的标准 LangChain retriever。

retriever 仅负责搜索。要创建实例并上传内容,请将其与 Cloudflare Python SDK ↗ 配合使用。本指南使用 Python SDK 创建 AI Search 实例、索引文件,并将 LangChain retriever 用作搜索工具。新实例默认使用混合搜索。

前提条件

  • Python ↗ 3.10 或更高版本
  • 你的 账户 ID
  • 同时具有 AI Search:Edit 和 AI Search:Run 权限的 API 令牌

要创建令牌,请按照 创建 API 令牌 操作,并添加这两项权限。Edit 用于预配实例并上传文件;Run 用于执行搜索。

1. 安装软件包

创建项目目录和虚拟环境,以隔离依赖项。

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 cloudflare

cloudflare SDK 用于创建实例并上传文件。langchain-cloudflare 包提供 retriever 以及 RAG 和智能体工具辅助函数。安装 langchain-cloudflare 也会安装 langchain-core,因此无需单独安装 langchain。

2. 设置凭据

导出你的账户 ID 和 API 令牌。Cloudflare SDK 会自动读取它们。

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

3. 创建实例

创建名为 main.py 的文件。新实例默认使用 混合搜索。由于未连接数据源,该实例使用 内置存储。

创建已存在的实例会失败,因此代码会先检查,仅在缺失时创建。

main.pypython
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 名称。

4. 上传并索引文件

将以下内容添加到 main.py,以上传文档到内置存储。在 file 参数中将 wait_for_completion 设为 True 会等待文件完成索引后再返回。

main.pypython
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;文件会在后台继续索引,并很快变为可搜索。

5. 查询实例

有三种从 LangChain 使用实例的方式。选择适合你应用的一种:

这三种方式都使用相同的 CloudflareAISearchRetriever,由第一种方式创建。

直接搜索

将 CloudflareAISearchRetriever 指向该实例。将 retrieval_type 设为 hybrid,以使用已启用的向量索引和关键词索引。

main.pypython
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。

将 AI Search 用作智能体工具

用 create_retriever_tool 包装 retriever,让智能体能够搜索你的内容。这是从 LangChain 智能体使用 AI Search 的推荐方式。

main.pypython
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 智能体。

构建 RAG 链

要根据检索到的内容回答问题,请将 retriever 与模型组合。本示例使用同一软件包中包含的 ChatCloudflareWorkersAI。以与 retriever 相同的方式传入账户 ID 和令牌。

由于此选项会调用 Workers AI 生成答案,此处传入的令牌还需要 Workers AI 权限。将其添加到你已创建的令牌中,或传入单独的令牌。

main.pypython
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 中使用

在 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")。

后续步骤

混合搜索

结合向量搜索与关键词搜索,并配置融合方式。

检索配置

调整筛选、重排序、查询改写和缓存。

这篇文档对您有帮助吗?