企业官网建设流程全解析

1. 先聊清楚：Agent 为什么非要联网不可

如果你跟我一样，过去半年在折腾各种 AI Agent，一定撞到过同一个尴尬场面：问它“帮我看看今天某品牌的发布会说了什么”，它一本正经地编出一段发布会通稿，时间、地点、嘉宾全都有，就是没一句是真的。

这不是模型笨，而是底层逻辑决定的。大语言模型的知识来自训练时拍进去的数据，存在一个固定的知识截止日期。截止日期之后发生的事情，它根本没见过。更麻烦的是，模型没有“我不知道”这个概念，遇到没见过的问题，它会按照概率分布顺理成章地生成一段看起来像答案的文字。这个在行业里有个专门的说法，叫“幻觉”，但实际体验就是一本正经地胡说八道。

所以我从一开始就坚信一个判断：Agent 要落地，第一件事不是把模型换得多大，而是给它接上有实时信息输入的管道。

这个管道的核心就是联网搜索能力。Agent 接收用户问题之后，先去网络上检索相关资料，再把检索结果连同问题一起交给模型，让模型基于真实信息作答。模型不再凭空推理，而是站在实时数据上做归纳和提炼，准确率完全不是一个级别。

但接搜索这件事，看起来简单，真正做起来坑不少。你要么自己写爬虫去抓网页，要么对接各种搜索服务的 API。而搜索 API 这个行的水很深，有的按次数收费贵得离谱，有的返回结果质量差到没法用，有的文档写得语焉不详，接入光调参就折腾一星期。

前阵子我注意到 Cloudflare 悄悄上线了 Web Search API，就专门花时间研究加实测了一轮。这 API 本身就是给需要联网能力的 Agent 场景设计的，直接通过 Cloudflare 的全球边缘网络发起搜索，拿回来的结果直接用结构化数据返回，还支持把结果做一轮模型重排。说白了，这就是“给 Agent 接上实时联网”的一个很顺手的方案。这篇文章把我从读文档到跑通、再到实际嵌入 Agent 工作流的完整过程都记录下来，顺便把里面踩到的坑一并交代清楚。

2. Web Search API 到底是啥：一个被低估的搜索入口

2.1 一句话理解它的定位

Cloudflare 本身是做全球网络基础设施的，它的优势从来不是“搜得多准”，而是“在世界各地的边缘节点上有极低延迟的响应能力”。Web Search API 就是基于这套基础设施做的搜索接口，让你不用自己搭搜索组件，直接调 API 就能拿到一组网页结果。

它的返回结果跟你在搜索引擎页面上看到的东西类似，包含标题、URL、描述这些结构化字段。区别在于，它是给程序用的，不是给浏览器用的。

在 Agent 场景里，这就意味着你的大模型应用可以随时发一个查询，拿到一组链接和摘要，然后再决定下一步怎么做。整个过程可以完全自动化，不需要人肉眼去看页面。

2.2 我关心的其实是那两个不同的调用模式

Cloudflare 这个 Web Search API 分两个层级，一个叫 Web Search，一个叫 Web Search Preview。官方文档写得很简短，但我实测之后发现差别非常大，这个必须单独拎出来说。

Web Search是完整版。你给它一个查询，它先执行搜索，然后把原始结果丢给配套的模型做一轮重排和提炼，最终返回的是一份经过模型处理过的、更结构化的答案。它天然适合“Agent 需要自己理解搜索内容”的场景。

Web Search Preview则是轻量版。它只做搜索，不做模型重排，返回原始网页标题和摘要列表。响应更快，成本更低，适合那些只需要拿到链接列表、后续自己处理结果的场景。

我当时看到这个区分就觉得很合理，因为这正好对应了 Agent 开发中的两种典型需求——有的 Agent 希望直接拿到答案，有的 Agent 更希望拿到材料自己做判断。

2.3 为什么我不建议自己写爬虫

可能有人会问，我直接写个脚本抓搜索引擎结果不就行了，何必多此一举？我在早期项目里确实这么干过，后来放弃了，原因有三条。

第一条是稳定性。搜索页面的 HTML 结构三天两头就变，你的解析规则刚调好就失效了，每周得花大量时间去修复。

第二条是反爬。搜索引擎对自动化抓取有严格的频率限制，到了某个阈值，你的 IP 就会被临时限制，整个流程直接瘫痪。

第三条是结构。你自己抓回来的 HTML 是一堆乱七八糟的标签和脚本，要从中提取出干净的标题、时间、正文，清洗成本非常可观。专业的搜索 API 直接把这些脏活干完了，返回给你的是结构清晰的 JSON。

顺带说一句，很多搜索 API 返回的数据本身就附带排名信号，比如来源域名权重、结果匹配度，这些信号能直接帮助 Agent 判断该优先信任哪一条结果。

3. 开通与鉴权实战：从创建账号到发出第一个请求

3.1 准备阶段最容易忽略的东西

要先说一个非常容易踩的坑：Cloudflare Web Search API 并不是单独的一个控制台入口，它属于 Cloudflare 的开发者平台服务。你需要在控制台里进入 Workers AI 相关的功能区，找到 Web Search 服务，确认你的账号已经绑定了支付方式。这一步很多人忽略，导致后面调用时碰到各种摸不着头脑的报错。

当然，实际操作中以你控制台里能看到的服务列表为准。我最初犯的错就是以为开完账号就能直接调 API，结果把 curl 命令发出去之后收到一条莫名其妙的错误，排查半天才发现是服务没激活。这个放在后面踩坑部分详细说。

3.2 创建 API Token 的权限细节

鉴权方式是标准的 API Token。在控制台的“My Profile → API Tokens”里创建，但这里有大学问——创建时选择的权限模板会直接影响你能调什么接口。

我一开始图省事，直接选了一个全局权限模板，结果安全上心里不踏实。后来调整成只给 Workers AI 相关权限，调用一切正常。这里我的建议是：权限范围能收多窄就收多窄，只勾选你实际要用的服务权限。Token 泄漏不可怕，可怕的是泄漏的 Token 拥有全量权限。

创建完成后，Cloudflare 会给你一次机会把 Token 完整复制下来，之后就不再显示了。务必立刻存到安全的地方，推荐放到你服务器环境变量里，别硬编码到代码里。

3.3 一个最小可运行的调用示例

下面这个 Python 示例是我跑通之后精简出来的，直接复制就能用。请求的核心是一个 POST，目标地址是你的账号 ID 加上对应的服务路径，鉴权头带Authorization: Bearer <你的TOKEN>。

import requests ACCOUNT_ID = "你的账号ID" API_TOKEN = "你的API_TOKEN" url = f"https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/@cf/cloudflare/... # 具体的服务路径以官方文档为准" headers = { "Authorization": f"Bearer {API_TOKEN}", "Content-Type": "application/json", } payload = { "query": "Cloudflare Web Search API price", "max_results": 5, } resp = requests.post(url, headers=headers, json=payload) data = resp.json() print(data["result"]["results"] if resp.status_code == 200 else data)

注意上面代码里我故意把服务路径省略了一部分。原因很简单，这类服务的具体调用路径和参数格式迭代比较快，我实测用的路径跟官方文档过一阵子可能对不上。你真正动手的时候，以 Cloudflare 官方文档里列出的 URL 为准，重点理解这个调用模式。

如果你不想先装 Python 环境，用 curl 验证更快：

curl -X POST \ "https://api.cloudflare.com/client/v4/accounts/你的账号ID/ai/run/服务路径" \ -H "Authorization: Bearer 你的TOKEN" \ -H "Content-Type: application/json" \ --data '{"query":"latest AI agent frameworks","max_results":5}'

返回 JSON 里有一组结果，每个结果包含标题、链接、描述和来源信息。从这个结构开始，你的 Agent 就已经具备联网感知能力了。

4. 参数拆解与结果处理：真正的分水岭在这里

4.1 query 怎么写，结果质量差一个档次

很多人以为 query 就是把用户的问题原样丢进去。我实测下来发现，这是结果质量最大的分水岭。

搜索引擎对自然语言的解析能力其实一般。你问“我想知道最近AI大模型的价格”，搜索引擎优先匹配的是“AI”“大模型”“价格”这些词，但网页返回顺序未必符合你的真实意图。相反，你把 query 改造成几个精准关键词，比如：

AI 大模型 API 定价 2026

效果会好非常多。这种差异在中文搜索里尤其明显，因为中文分词机制对长句的理解本身就有损耗。

我的做法是在 Agent 里内置一个 query 改写环节：模型把用户的自然语言问题先改写成一个适合搜索引擎的关键词组合，再拿去搜索。这一步多消耗一点 token，但换来的是结果质量的巨大提升。

4.2 领域与语言偏向：别忘了返回结果的本地化

这是我在实测中发现的另一个细节。Web Search API 的参数里可以设置地域和语言偏好，但实际测试下来，如果你不主动控制，返回结果的本地化程度会很不稳定。

举个我实际遇到的情况：不带任何地域参数搜索“附近电动车充电桩政策”，返回的结果里有不少英文页面，明显是面向国际用户的。但对于中国用户来说，本地政策信息才是真正有用的。这时候需要在请求参数里加上对应的地域和语言限定，结果列表会立刻变成以中文来源为主的页面。

我的建议是：在调用 API 之前，先判断用户问题的语言，再根据语言设置对应的地域偏好和结果语言。这本质上是一个很简单的映射逻辑，但对体验的提升是肉眼可见的。

4.3 返回内容的基本结构：哪些字段真正有用

Web Search API 返回的数据结构里，字段比你想的要多，但核心就几个。我平时只关注 4 个：

• 标题：用于展示和快速判断内容主题。
• URL：用于做深入页面抓取（如果后续还需要读取全文的话）。
• 描述/摘要：这是 Agent 做答案生成的主要材料，节省了大量网页读取成本。
• 来源信息：包括来源站点本身的信息，可用于判断可信度。

特别提醒一点：描述字段并不一定完整覆盖网页的全部内容。搜索引擎截取的摘要有时候只展示了网页某个角落的片段，但这已经够用了。更关键的是，你不需要为每一个结果都打开网页抓取全文，摘要足够应对大部分问题，这也是搜索 API 省成本的核心原因。

对于需要读取全文的场景（比如深度研究类 Agent），正确的顺序是：先用 Web Search 找到候选 URL，再用自己的页面抓取模块选择性抓取排名前几的页面。不要一上来就全量抓取，那样成本和延迟会爆掉。

4.4 结果排序与截断策略：把“相关”变成“有用”

拿到返回结果之后，我强烈建议不要直接全量塞给大模型。理由是：搜索 API 返回的结果按常规相关性排序，但相关性不等于可用性。有些结果标题看着相关，实则是三年前的旧闻；有些结果摘要内容互相重复；还有些结果来源明显是低质量内容农场。

我的实测策略是三层过滤：

第一层，时间过滤。如果查询涉及时效性内容（比如新闻事件、政策变化、价格信息），优先保留摘要中带近期时间表述的结果。第二层，去重。多个 URL 指向同一来源或摘要内容高度相似时，只保留一个。第三层，来源质量。对来源做白名单/黑名单判断，比如我个人会偏好官方站点、权威媒体，对纯 SEO 聚合站打低分。

这三层过滤用代码实现并不复杂。但效果非常直接——丢给大模型的内容变干净了，生成答案时的幻觉率大幅下降。

5. 把搜索能力真正嵌进 Agent 工作流：实践与取舍

5.1 关键决策：什么时候触发搜索

接入 API 只是第一步，真正难的是搞清 Agent 在什么情况下需要搜索。如果你让 Agent 每轮对话都先搜索一把，延迟和成本都受不了。但如果完全依赖模型内部知识，那搜索能力又等于白接。

我这里用的策略是意图判断，具体来说就是让模型自己决定要不要搜索。在系统提示词里预设一条指令，要求模型判断用户问题是否存在以下情形之一：涉及实时信息、涉及训练截止日期之后的事件、涉及具体的价格或参数、涉及用户没有明确给出上下文的公共事件。满足任意一条，就调用搜索工具；否则直接回答。

这套逻辑实现起来其实就是给模型一个搜索工具，然后依赖函数调用机制来触发。实测下来，触发准确率能达到七八成，剩下两成多是因为模型把一些明明可以用内部知识回答的问题也拿去搜索了，属于过度搜索。但过度搜索的代价比不搜索少得多，至少答案不会编造。

5.2 Prompt 注入：别把搜索材料随便糊上去

拿到搜索结果之后，把它们直接往里一塞就完事？这是我见过最多人犯的错。

搜索结果是一堆碎片信息，可能来自不同立场、不同时间、不同质量的来源。如果你直接把这一堆东西原样塞进模型上下文，模型的输出会变得非常不稳定，甚至会因为相互矛盾的搜索摘要而给出摇摆不定的答案。

我的做法是为搜索结果设置一个专门的上下文区域，用清晰的分隔标记，并给每条结果编上序号和来源标签。然后在提示词里告诉模型：以下内容来自实时搜索结果，你应当优先参考带编号的内容，并在回答中标注信息来源序号。

贴一下我用的提示词片段：

以下是实时搜索结果，每个条目以 [R1]、[R2] 等编号开头。 回答以下问题时，请仅依据这些检索结果提供的信息，同时在文末列出你引用的编号。 如果检索结果中没有你需要的信息，请明确回答“搜索结果未覆盖该信息”，不要自行推测。

这个设计有两个直接红利：第一，模型的回答可溯源，用户能点开链接验证，信任度显著提升；第二，当搜索结果与模型内部知识冲突时，模型有明确指令优先采纳检索结果，而不是凭借内部记忆硬撑。

5.3 缓存与降本：每次都搜索是最愚蠢的做法

我一度天真地以为反正按次计费，多搜几次无所谓。后来拿到账单才发现，高频调用场景下搜索成本累积起来相当夸张。于是我开始做结果缓存。

具体思路是：对于同一用户的重复问题（哪怕是不同话术表达），先在本地存一份查询到结果的映射。如果命中缓存并且缓存时间没有过期（一般设 10 到 30 分钟），就直接返回缓存结果，不再调用 API。只有缓存缺失时才走实时搜索。

这个策略对两类 Agent 特别有效：一类是客服机器人，用户反复问的是同样几个问题；另一类是资讯聚合类 Agent，同一时段内多条会话问的几乎都是同一个热点事件。加一层缓存之后，搜索 API 的调用量大概能砍掉一半以上。

5.4 多轮对话里的上下文衔接

多轮对话场景比单轮要复杂一些，因为用户的后续问题往往省略了上下文。比如用户先问“帮我查一下最近发布的 AI 手机”，你搜了一轮；接着用户问“那这款的续航怎么样？”，如果你直接拿这句话去搜索，搜索引擎根本不知道“这款”指的是哪款手机。

所以我在多轮架构里做了一个很关键的处理：每轮搜索之前，先把对话历史里最近几轮的信息压缩成一段“搜索上下文”，加到 query 前面。比如上面这个例子，实际发出去的 query 是“最近发布的 AI 手机 X1 续航表现”，而不是“续航怎么样”。

这个办法没有增加任何额外的 API 调用，只是把 Prompt 组装逻辑改了一下，但效果立竿见影。对话类 Agent 在此之后很少再出现因为缺少上下文而搜出一堆无关结果的状况。

6. 实测踩坑记录：这些问题官方文档不会告诉你

6.1 首次直接调用被 403：服务激活问题

我的第一个踩坑经历是 403 报错。那时候我刚创建完 Token，兴致勃勃地复制了 curl 命令准备跑第一个请求，结果返回 403 Forbidden。

我当时第一反应是 Token 权限不够，去控制台重新生成好几遍 Token，权限一路加到全量，问题依旧。后来才发现，问题根本不在 Token，而是 Web Search 服务在我的账号下没有正式激活——API 地址已经存在，但服务并没有在账号层面开通，自然拒绝请求。

这个问题的排查看起来费时间，实际上就是去控制台把对应服务启用一下、绑定账户即可。如果你碰到类似 403，别急着怀疑 Token，先检查服务本身的状态。

6.2 限流与 429：别等到被卡死了才看文档

另一个高频问题是 429 限流。免费额度阶段调用频率比较高的话，很快会触发限流。官方约定俗成是按账号维度计算调用频率，超出后返回 429。

我的处理方式是做两层防护。第一层是客户端限流：在代码里控制每分钟的调用总量，宁可排队也不要突发请求。第二层是重试退避：捕获 429 响应之后，不做即时重试，而是等待若干秒后再试，最多重试三次。如果还是 429，就让 Agent 告诉用户“当前搜索服务繁忙，请稍后再试”，而不是无限重试导致雪上加霜。

另外，限流也受你当前账号套餐影响。免费档和付费档的额度上限完全不同，建议在正式上线前先确认自己账号档位的配额数字，合理评估调用量。

6.3 返回结果的时效陷阱：搜索到了不等于新闻是新的

这是我用下来觉得最值得警惕的坑。Web Search API 返回的结果排序主要看相关性，不保证时效性。搜索一个最近刚发生的事件时，返回列表里可能混入大量几周甚至几个月前的内容，而且它们在列表中的排位还不低。

排查完我发现原因也不难理解：网页的发布时间并不总是显式标记在摘要里，搜索引擎只能靠页面内容和 URL 特征去推断，推断错了排位自然就不对。

应对办法是在结果处理阶段做一层时间判断：从摘要文本中提取时间描述（“昨日”、“本周”、“2026 年 1 月”等措辞，或 URL 上带的日期），再结合结果的来源分类给出一个时间置信分，过滤掉明显不满足时效要求的结果。这个办法不能 100% 命中，但能把时效性错误率降低一个量级。

6.4 摘要内容被噪声污染：来自 SEO 站的“伪相关”结果

这个坑对接入效果影响最大。搜索“为什么我的服务器总是断连”，返回结果里经常混进来一批 SEO 聚合站，标题看着很对症，点进去却是一堆工具广告和无关内容堆砌，摘要也是东拼西凑的。

我还发现一个规律：这类低质结果往往集中出现在某些特定域名后缀和特定站点结构上，因为它们批量生产页面、批量被搜索引擎收录，自然容易占据结果位置。长期使用之后可以慢慢积累一个黑名单域名列表，在前置过滤阶段直接剔除。

黑名单的好处不只是过滤低质结果，还能显著降低下游摘要生成的噪声干扰。Agent 不用再花力气辨别哪条摘要能信哪条不能信，回答内容的稳定性和可读性都会跟着上升。

6.5 成本预估：免费额度耗尽之后到底贵不贵

如果只是自己写个小项目玩，免费额度完全够用；但要上线服务，成本预估就得摆到桌面上。Cloudflare 的 Web Search API 计费是按照每次搜索以及重排所用的模型资源分别算的，实际成本跟你的调用量强相关。

我的估算经验是：一个中等体量的 Agent 应用（每天大概几千次搜索请求），月成本基本在可接受的范围内，比商业搜索服务便宜很多。但如果你把“每轮对话都搜索”当成默认行为，成本会快速膨胀。这也是我在第 5 章强调缓存和搜索触发策略的原因——用得好，成本是可控的；用不好，隐形成本很容易超出预期。

7. 一点个人总结

折腾完 Cloudflare Web Search API、把它暂时接入自己的模拟项目之后，我最大的感受是：实时联网搜索这件事，已经从一个“加分项”变成了 Agent 方案的“必有项”。

但这篇文章写到最后，我更想表达的是：API 本身永远只是工具，真正的价值在你怎么设计搜索触发机制、怎么清洗结果、怎么构造 Prompt 上下文。同样的 API，有人接出来是高级玩具，有人接出来是可落地产品，差距全在这些细节里。

给还没动手的读者一句实在话：别追求一步到位，也别一上来就搞复杂的 RAG 流程。先打通 API，拿到一批真实搜索数据，观察结果质量，再从简单的函数调用开始接入 Agent。等你跑通了第一条链路，后面的事情会水到渠成。