Cloudflare AI Search 生产级实战模式从 search() 到多租户、流式与重排的完整指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以cloudflare-deploy技能库中 patterns.md 为骨架系统讲解 Cloudflare AI Search原 AutoRAG托管式语义检索与 RAG 服务在生产环境中的核心使用模式search()与aiSearch()的方法选型、基于文件夹的多租户隔离、流式响应、评分阈值调优、System Prompt 模板、复合过滤与重排序。读完本文你将能在 Cloudflare Workers 中独立搭建一套可用于文档问答、企业知识库与多租户 SaaS 场景的检索增强生成管线。一、模式总览何时用哪个方法AI Search 的核心 API 通过 Workers 上的env.AI.autorag(实例名)暴露两种检索方法二者返回内容与适用场景截然不同是后续所有模式的基础适用场景方法返回值典型延迟自定义 UI、数据分析search()仅原始分块Raw chunks约 100–300ms聊天机器人、问答aiSearch()AI 生成回答 检索分块约 500–2000ms// 仅获取检索结果自己渲染 UI 或做统计 const results await env.AI.autorag(my-search-instance).search(options); // 直接获得 AI 回答内部自动完成检索 生成 const answer await env.AI.autorag(my-search-instance).aiSearch(options);选择建议需要最终答案聊天、QA、客服助手→ 用aiSearch()返回的response字段即为生成结果data字段附带检索到的分块可同时用于回答 引用来源需要原始检索结果自建结果页、埋点分析、对 chunk 二次加工→ 用search()延迟更低、不消耗 LLM 生成。从 api.md 可见aiSearch()返回结构为{ search_query, response, data, has_more, next_page }其中search_query是实际用于检索的查询词开启rewrite_query后可能是改写后的版本data中每条SearchResult包含id、score、content以及metadata: { filename, folder, timestamp }。这正是回答 证据模式的数据基础。二、查询改写rewrite_query 的正确开关rewrite_query控制是否让 LLM 先对用户查询做改写纠错、补全、语义归一再执行检索设置使用时机true用户输入可能含拼写错误、含糊查询falseLLM 生成的查询已经过优化const answer await env.AI.autorag(docs).aiSearch({ query: how do i configre cachign?, // 拼写错误场景 model: cf/meta/llama-3.3-70b-instruct-fp8-fast, rewrite_query: true });关键注意点结合 api.md默认值为false不是true。如果你的用户输入质量参差务必显式开启当你的上层 Agent 或 LLM 已经生成精确查询时开启改写反而会引入额外延迟甚至改变语义此时保持false开启后响应中的search_query字段会反映改写后的查询词可用于日志与排障。三、多租户隔离基于文件夹的前缀过滤AI Search 自动索引的内容会带上folder元数据见 configuration.md 中Auto-indexed metadata说明。多租户场景下让每个租户的文档位于独立目录如tenants/{tenantId}/再用过滤器做前缀匹配即可实现逻辑隔离无需为每个租户建实例const answer await env.AI.autorag(saas-docs).aiSearch({ query: refund policy, model: cf/meta/llama-3.3-70b-instruct-fp8-fast, filters: { column: folder, operator: gte, // starts with pattern value: tenants/${tenantId}/ } });这里有两个容易被忽略的实现细节见 gotchas.md文件夹前缀匹配必须用gte而非eqgte大于等于在字符串比较语义下能命中tenants/abc/...的全部嵌套子路径实现以该前缀开头的所有文件若用eq只能精确匹配单个路径确保tenantId来自可信来源将租户 ID 直接拼进过滤器值前应做校验/转义避免被构造出跨越租户目录边界的前缀。可用过滤器操作符完整列表见 api.mdeq、ne、gt、gte、lt、lte内置元数据字段为filename、folder、timestampUnix 秒。四、流式输出SSE 实时返回聊天型产品要求逐字返回aiSearch()支持stream: true直接返回可读流配合text/event-stream响应头即可完成 SSE 流式问答const stream await env.AI.autorag(docs).aiSearch({ query, model: cf/meta/llama-3.3-70b-instruct-fp8-fast, stream: true }); return new Response(stream, { headers: { Content-Type: text/event-stream } });要点说明stream选项默认值为false见 api.md流式场景需显式开启该模式与 Workers 的Response天然契合前端可用标准EventSource或fetchReadableStream消费若需要在流式输出过程中再叠加自定义格式如把 chunk 包装成data: {...}\n\n可参照 workers-ai/patterns.md 中 Stream → TransformStream 的写法原理一致。五、评分阈值Score Threshold 的三档调优score_threshold用于过滤低相关分块取值 0.0–1.0默认 0.3。它在召回率与精确度之间做权衡阈值适用场景0.3默认广泛召回Broad recall探索型查询0.5均衡Balanced生产环境推荐默认值0.7高精确度High precision关键准确性场景const answer await env.AI.autorag(docs).aiSearch({ query, model: cf/meta/llama-3.3-70b-instruct-fp8-fast, ranking_options: { score_threshold: 0.5 } });调优路径结合 gotchas.md检索结果为空时先降阈值按移除过滤器 → 阈值降到 0.1 → 检查索引是否已填充三步排查逐步定位是过滤条件、阈值还是索引的问题响应过慢3s时提高阈值并限制数量配合max_num_results默认 10一起使用减少送入 LLM 的分块数量从而降低生成延迟与 token 成本阈值调优本质上是在宁可漏、不可错与宁滥勿缺之间选择法律、金融等高风险回答用 0.7探索式问答用 0.3。六、System Prompt 模板约束生成行为aiSearch()支持通过system_prompt传入系统提示词约束 LLM 的生成这是控制幻觉、要求仅基于检索内容回答的关键手段const systemPrompt You are a documentation assistant. - Answer ONLY based on provided context - If context doesnt contain answer, say I dont have information - Include code examples from context; const answer await env.AI.autorag(docs).aiSearch({ query: How do I configure caching?, model: cf/meta/llama-3.3-70b-instruct-fp8-fast, system_prompt: systemPrompt });为什么这套模板有效仅基于上下文回答直接约束 LLM 不引用检索范围之外的知识是 RAG 管线控制幻觉的第一道防线无答案时明确表态避免模型强行编造输出更诚实、可审计包含上下文中的代码示例对文档类问答尤为重要——用户问的是配置方法回答应尽量附上真实代码片段而非泛泛描述。system_prompt字段在 api.md 的AiSearchOptions接口中为可选参数。若你的业务有多个产品线可将 prompt 模板做成配置文件按环境切换与下文的多环境管理配合使用。七、复合过滤器OR / AND 的写法与限制当单字段过滤不够时AI Search 支持and/or复合过滤器最多嵌套 2 层每个复合过滤器内最多 10 个子过滤器平台限制见 gotchas.md。OR多个文件夹命中例如文档站的多模块搜索filters: { operator: or, filters: [ { column: folder, operator: gte, value: docs/api/ }, { column: folder, operator: gte, value: docs/auth/ } ] }AND文件夹 时间范围例如只检索最近一周的新文档filters: { operator: and, filters: [ { column: folder, operator: gte, value: docs/ }, { column: timestamp, operator: gte, value: oneWeekAgoSeconds } ] }⚠️ OR 操作符的硬性限制务必注意否则请求会报校验错误or只能用于同一列且子过滤器的operator只能是eq跨文件夹的 OR 用eq 同列枚举即可例如{ operator: or, filters: [{column:folder, operator:eq, value:docs/}, {column:folder, operator:eq, value:guides/}] }是合法写法而gt/gte混入 OR 则不合法and组合没有该限制可混合不同列、不同操作符。时间戳精度陷阱timestamp使用 Unix秒10 位数字不是毫秒。计算时务必用Math.floor(Date.now() / 1000)见 gotchas.md用毫秒值会导致时间过滤完全失效。八、重排序Reranking 提升高价值场景精度默认检索按向量相似度排序但语义相关未必等于对当前问题最有用。重排序Reranking让一个交叉编码器对初筛结果二次打分显著提升答案质量代价是额外约 300ms 延迟reranking: { enabled: true, model: cf/baai/bge-reranker-base }适用决策启用高价值场景high-stakes如法律、医疗、金融问答或对回答准确性有硬性要求的客服系统——多花 300ms 换取更可靠的结果不启用延迟敏感、探索型或大规模低价值流量场景默认向量排序已足够。reranking与score_threshold可组合使用先用阈值粗滤掉低质量分块再对保留项重排兼顾成本与精度。九、把模式组装起来一个生产级 Worker 示例将上述模式组合可以得到一个同时具备多租户隔离、流式输出、阈值控制与重排的完整问答端点export default { async fetch(request: Request, env: Env): PromiseResponse { const { query, tenantId } await request.json{ query: string; tenantId: string }(); const stream await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({ query, model: cf/meta/llama-3.3-70b-instruct-fp8-fast, rewrite_query: true, // 用户输入场景开启改写 system_prompt: You are a documentation assistant. - Answer ONLY based on provided context - If context doesnt contain answer, say I dont have information - Include code examples from context, ranking_options: { score_threshold: 0.5 }, // 生产默认阈值 reranking: { enabled: true, model: cf/baai/bge-reranker-base }, filters: { column: folder, operator: gte, value: tenants/${tenantId}/ // 多租户前缀过滤 }, stream: true }); return new Response(stream, { headers: { Content-Type: text/event-stream } }); } };配套的 Worker 绑定与环境配置见 configuration.md// wrangler.jsonc { ai: { binding: AI } }# wrangler.toml 多环境隔离 [env.production.vars] AI_SEARCH_INSTANCE prod-docs [env.staging.vars] AI_SEARCH_INSTANCE staging-docs生产级补充建议源自 gotchas.md 的反模式清单实例名用环境变量而非硬编码env.AI.autorag(env.AI_SEARCH_INSTANCE)避免多环境误连区分捕获错误类型AutoRAGNotFoundError实例不存在404 语义与AutoRAGUnauthorizedErrorToken 无效/缺失401 语义分别处理不要笼统 catch实例名拼写核对AutoRAGNotFoundError最常见根因是实例名与 Dashboard 中的不一致先核对再排查其他索引实时性认知索引每 6 小时自动刷新支持手动 Force Sync30 秒限频不适合秒级更新场景需要实时内容的场景请评估 vectorize 手动向量化方案详见 README.md 的 AI Search vs Vectorize 对比。十、附本文涉及的完整参考文档参考文档内容ai-search/README.md产品定位、快速开始、平台限制每账号 10 实例、每实例 10 万文件、单文件 4MBai-search/api.mdaiSearch()/search()全参数、响应结构、操作符、REST APIai-search/configuration.mdWorker 绑定、R2/网站数据源、路径过滤、多环境、监控ai-search/gotchas.md类型安全、过滤器限制、索引问题、性能与反模式ai-search/patterns.md本文骨架方法选型、改写、多租户、流式、阈值、Prompt、复合过滤、重排本文所有代码示例均可直接复制到 Cloudflare Workers 项目中使用实际部署前请确认账号已开通 AI Search 服务并按 configuration.md 完成 AI binding 与数据源配置。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考