让 AI Agent 真正搜到你的数据：Cloudflare AI Search 的使用思路与接入实践

2026-08-31 33 预计阅读时间: 1 分钟
来源: infoq.com AI 摘要 Original link

Disclaimer: This article is an AI-assisted summary. Read it together with the original source when precision matters. The summary may omit context, version differences, or edge cases and is not official documentation.

预计阅读时间：10 分钟

当企业把 AI Agent 接入内部文档、产品资料或多媒体内容时，真正棘手的问题往往不是生成答案，而是让模型稳定找到正确的数据。Cloudflare AI Search 将搜索与检索能力做成可直接使用的服务，让 Agent 和应用可以围绕自定义数据建立搜索入口，并进一步与 Cloudflare 的其他工具组合。

从“让模型知道”转向“让模型搜到”

直接把全部业务数据塞进提示词并不可行：上下文窗口有限，数据更新会产生同步成本，敏感内容也不应该无条件暴露给模型。更合理的架构是把搜索作为 Agent 的一个工具：

  1. 用户提出问题。
  2. Agent 判断是否需要查询外部数据。
  3. Agent 调用 AI Search 检索自定义内容。
  4. 应用将检索结果作为上下文交给模型生成回答。
  5. 最终答案保留来源或文档标识，方便审计和追溯。

这种方式把“知识更新”和“回答生成”解耦。业务数据发生变化时，重点是更新索引或数据连接，而不是重新训练模型。

从产品定位看，它更像是 AI 应用的基础检索层，而不是一个只服务于人工搜索框的站内搜索组件。

面向 Agent 的搜索工具

Agent 可以把搜索能力当作工具调用。对于“查找退款政策”“比较两个产品规格”“从内部手册中定位操作步骤”这类任务，Agent 不需要预先掌握全部内容，只需要在需要时检索相关数据。

实际接入时，建议明确工具的输入和输出边界：

  • 输入包含自然语言查询，以及可选的租户、权限、语言或内容类型过滤条件。
  • 输出只返回必要的标题、片段、标识符和相关性信息。
  • Agent 提示词要求它优先使用检索结果，不要在证据不足时自行补全。

多模态检索

如果业务数据不只有纯文本，例如产品图片、PDF、截图或其他媒体内容，多模态搜索可以减少“先人工描述，再进行文本搜索”的中间步骤。可以这样设计：用户上传图片或提出文字问题，检索层返回相关的文本和媒体结果，模型再负责组织说明。

不过，多模态能力并不意味着可以忽略数据治理。图片中的个人信息、合同中的敏感字段、旧版本产品资料，都需要在进入搜索系统前明确保留策略和访问控制。

与 Cloudflare 工具组合

AI Search 的价值还在于它可以成为 Cloudflare 应用体系中的一个检索环节。一个常见组合是：边缘层负责接收请求和执行访问控制，应用层负责会话与 Agent 编排，搜索层负责定位自定义数据，模型层负责生成最终回复。

这种拆分有两个好处：搜索服务可以被多个应用复用；Agent 的业务逻辑也不会和某个具体数据源完全耦合。

一个可改造的 Agent 搜索适配器

下面的示例使用 Python 标准库之外的 requests，演示如何把搜索服务包装成 Agent 可以调用的工具。示例中的 endpoint、认证头和响应字段是适配层假设，实际使用时请按照你的 Cloudflare AI Search 配置替换；代码本身可以直接运行，只要提供一个兼容的 HTTP 搜索接口。

安装依赖：

python -m pip install requests
export SEARCH_ENDPOINT="https://search.example.com/query"
export SEARCH_TOKEN="replace-with-your-token"

保存为 search_tool.py：

import json
import os
import sys
from typing import Any

import requests


ENDPOINT = os.environ["SEARCH_ENDPOINT"]
TOKEN = os.environ["SEARCH_TOKEN"]


def search_custom_data(query: str, limit: int = 5, content_type: str | None = None) -> list[dict[str, Any]]:
    payload = {
        "query": query,
        "limit": limit,
    }
    if content_type:
        payload["filter"] = {"content_type": content_type}

    response = requests.post(
        ENDPOINT,
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=15,
    )
    response.raise_for_status()
    data = response.json()

    # 将供应商响应统一成 Agent 易于消费的格式。
    return [
        {
            "id": item.get("id"),
            "title": item.get("title", ""),
            "snippet": item.get("snippet", item.get("text", "")),
            "url": item.get("url"),
        }
        for item in data.get("results", [])
    ]


if __name__ == "__main__":
    question = " ".join(sys.argv[1:]).strip()
    if not question:
        raise SystemExit("用法: python search_tool.py '你的问题'")

    print(json.dumps(search_custom_data(question), ensure_ascii=False, indent=2))

运行：

python search_tool.py "如何处理企业客户的退款申请？"

在真正的 Agent 编排中，可以把 search_custom_data 注册为工具，并把返回的 title、snippet 和 url 放入模型上下文。不要把整个原始文档无差别传给模型；先限制结果数量，再根据任务需要获取完整内容。

落地时最容易忽略的边界

权限必须在搜索前生效

如果同一个搜索索引服务多个团队，不能只依赖模型“自觉不回答”。租户、用户角色、文档空间等过滤条件应该由应用在调用搜索时注入，并在服务端校验。搜索结果一旦泄露给模型，就已经超出了后续提示词能够弥补的范围。

检索质量要单独评估

回答看起来流畅，不代表检索结果正确。建议准备一组真实问题，记录：

  • 正确文档是否出现在前几条结果中。
  • 旧版本内容是否被错误优先返回。
  • 同义词、缩写和多语言查询是否有效。
  • 图片、PDF 等非纯文本内容是否能被找到。
  • 没有答案时，系统是否会明确承认缺少依据。

多模态数据要建立生命周期

媒体数据通常体积更大，也更容易包含隐私信息。上线前应确定哪些文件可以被搜索、谁能搜索、索引何时更新，以及删除原文件后搜索结果多久消失。

一份实用的采用清单

  • 先选一个边界清晰的数据集，例如产品帮助中心或内部操作手册。
  • 为每条数据保留稳定的文档 ID、标题、版本和权限元数据。
  • 把搜索封装成独立工具，不让每个 Agent 自己拼接检索逻辑。
  • 对文本和媒体内容分别准备评测问题。
  • 在提示词中要求基于检索证据回答，并处理“没有结果”的情况。
  • 记录查询、返回文档和最终回答，便于发现权限与质量问题。
  • 先以只读问答上线，再逐步扩展到需要执行操作的 Agent。

Cloudflare AI Search 的核心意义不是让模型凭空获得更多知识，而是为 Agent 和应用提供一条面向自定义数据的可靠搜索路径。把检索、权限、数据生命周期和回答生成分开设计，才能让这项能力从演示功能变成可维护的生产组件。

# AI # Cloudflare # InfoQ # LLM # 云平台 # 全栈 # 数据工程

相关推荐