kapa.ai：文档导入、Retrieval 与 Blog 接入流程

AI 参与说明（Agent：Codex）：本文由 Codex 根据 kapa.ai 官方文档协助调研、撰写和校验，资料整理于 2026-09-08。Blog 用作公开文档站点的接入案例；选型顺序属于工程建议。运行记录：模型 gpt-6-astra，reasoning effort medium，执行入口 Codex Desktop，提供方 openai，CLI 版本 0.153.4（不代表桌面 App 版本）。

修订说明（2026-09-10，Agent：Cursor）：补充与 Cloudflare AI Search 的选型对比及 Blog 场景工作量差异。AI Search 事实依据 Context7（/websites/developers_cloudflare_ai-search）与 Cloudflare 官方文档核验；kapa 侧沿用既有一手资料。模型标识与 reasoning effort 未取得运行记录；执行入口 Cursor。

修订说明（2026-09-11，Agent：Cursor）：突出 Website Widget 可直接嵌入与 AI Search 需自建（或另接 UI snippets）搜索 / 对话界面的工作量差异，并据此调整选型结论权重。AI Search UI snippets 依据官方 “Add search to your website” 与 Context7 核验。模型标识与 reasoning effort 未取得运行记录；执行入口 Cursor。

阅读前先看这几个词

把现有文档交给 AI 使用，需要先解决内容怎样进入知识库，再解决问题怎样找到相关内容。kapa.ai 同时提供这两部分能力。下面的名称贯穿全文，中文名称用于阅读对照。

核心判断：先选内容入口，再选使用入口

Kapa indexes connected knowledge sources and exposes Retrieval through HTTP API or MCP. Retrieval returns ranked Chunks with source URLs; the consuming agent generates the final answer. 官方概览、Agentic retrieval

因此，接入时有两个独立选择：

• 内容入口：File Upload、Web Crawling、S3 Storage、GitHub Code 等决定资料从哪里来。
• 使用入口：Retrieval API、Hosted MCP server、Website Widget 等决定谁来查询，以及是否直接提供问答界面。

同一个 Project 可以包含多个 Source，并供不同使用入口查询。上传文档后不必立即做聊天机器人，也可以先检查 Retrieval 返回的原始内容；反过来，只安装 Website Widget，也不会自动完成知识库建设。

对于已经发布的 Blog 文档，本文建议从 Web Crawling → 检查 Retrieval → 选择界面 开始。若后续需要更严格地控制正文格式、入库范围或更新节奏，再评估 S3 Storage。这个顺序减少了首次评估时需要同时处理的问题，不代表 Web Crawling 在所有项目中都优于文件导入。

Search 到底在搜索什么

Ingestion 与查询是两条链路

下图表达职责关系，不表示 kapa 已公开全部内部算法或各步骤的固定实现顺序。

flowchart TB
    sources["Source<br/>网页、文件或存储桶"] --> ingestion["Ingestion<br/>解析内容并建立索引"]
    ingestion --> index["Project 的知识索引"]
    index -->|"用户提交问题后查询"| retrieval["Retrieval<br/>寻找并排序相关 Chunks"]
    retrieval --> context["Chunks 与 source_url"]
    context --> results["应用展示结果<br/>或 Agent 生成回答"]

用户提问时，kapa 查询的是 Ingestion 维护的索引。它不会因为收到一个问题，就重新遍历整个网站或存储桶。内容更新需要先被 Connector 发现，再同步到索引；所以“源文件已改”和“新内容已经可搜”之间存在时间差。How data ingestion works

以 Blog 为例，读者输入“多个请求之间需要共享状态，应该看哪些文章”，Retrieval 的任务是返回与问题相关的 Chunks 及其文章地址。应用可以直接展示这些结果，也可以把它们交给 Agent，组织成带出处的解释。

不只是一次 Embedding 相似度查询

kapa 官网列出 Chunking、Embedding、Hybrid Search、Reranking 等托管能力。它们分别处理如何拆内容、如何表示语义、如何找到候选内容，以及如何让更相关的结果靠前。官网能力说明

这对技术文档很有意义：搜索精确 API 名称时，文字匹配很重要；用中文描述一个问题、却不知道文章中的英文术语时，语义匹配更有帮助。不过，这只是对能力作用的解释，不能据此推导出 kapa 使用某个特定数据库、某个固定模型或某套公开可复刻的排序算法。

可选的 Pruning 会在后续进一步过滤结果。use_pruning: true 会增加一次小模型调用，从已找到的 Chunks 中过滤低相关内容；它的目标是减少交给 Agent 的上下文，而不是生成最终回答。HTTP API

Retrieval、旧 Search 和 Chat API 不要混用

The legacy Search endpoint is deprecated. New integrations should use the Retrieval endpoint. HTTP API：Search (deprecated)

Retrieval 与 Documents、Chat API reference、Website Widget

Documents endpoint 匹配的是已入库的来源，并不是通用网页抓取器。给它一个知识库中不存在的 URL，不会让它现场上网读取该页面。

内容导入方式：Blog 应怎样选择

除这些入口外，kapa 还提供面向 Slack、Notion、Confluence、工单等内容的 Connectors；不必先把所有资料转换成一个大文件。Connectors

File Upload：最快验证单篇文章

后台依次选择 Sources → Add new source → File Upload，给 Source 命名，选择文件并上传。

当前 File Upload 格式表列出 .md、.txt、.docx、.pdf，以及特定用途的 OpenAPI 文件和 StackOverflow 导出文件。单文件要求小于 32 MB；.json 或 .csv 出现在表中，不代表任意 JSON 数据或任意 CSV 表格都按通用文档处理。File Upload

对于 Blog，可以先取几篇已公开文章，检查段落、代码和链接是否正确。但长期逐篇上传会产生一份需要手动维护的内容副本。原文修改后，要重新上传；不要期待它自动追踪本地文件或 Git 提交。

还有一个格式边界：File Upload 的格式表没有列出 .mdx，而 S3 Storage 和 GitHub Code 明确列出了。不能把一个 Connector 的格式支持套到另一个 Connector 上。

Web Crawling：从读者实际看到的页面开始

以本站公开文档入口 https://yindongliang.com/docs/ 为例，可按以下流程配置：

1. 在 kapa 创建或选择 Project，进入 Sources → Add new source。
2. 选择 Web Crawling；入门指南的界面也使用 Website Crawl 这一名称。
3. 输入 Start URL，先把范围限定在文档或一个专题，运行 Crawl。
4. 检查 Accepted 与 Skipped：确认该进来的文章存在，并理解被跳过的原因。
5. 设置正文选择器，点击 Convert，查看转换后的 Markdown。
6. 检查多篇页面后保存，进入 Needs review，审阅待入库内容。
7. 点击 Ingest，等待索引完成，再开始查询。

Index your first source

Crawl Preview 确认页面范围，Source Preview 确认页面里取了什么。 只检查 URL 列表，不能发现正文被截断、代码丢失或侧栏混入的问题。

Blog 的文章应优先选取正文容器。若页面 HTML 为正文设置了 article 与 data-pagefind-body，可以从下面这个 CSS selector 开始测试：

article[data-pagefind-body]

这是选择器候选示例，不是任意文档站点都适用的配置。需要在真实页面的 Source Preview 中确认：标题、代码块和表格存在，侧栏、页脚和评论未混入；目录入口、文章详情页也可能使用不同结构。

Web Crawling 支持 sitemap、多起始 URL、URL 包含/排除规则和按需启用 JavaScript rendering。URL 规则默认按字面子串匹配，启用对应选项后才按正则解释。对已输出完整 HTML 正文的页面，可以先关闭 JavaScript rendering，减少抓取成本；内容确实依赖客户端执行时再开启。Web Crawling

这条路线的主要优势是：读取的内容接近公开阅读版本，引用可以直接回到文章网页。对于包含特殊链接语法或组件调用的源文件，先由站点生成网页，也能减少直接读取源文件时的语法噪声。不过，动态交互状态仍需要抽样检查，不能假设网页中所有可操作体验都会被转换成完整文字。

S3 Storage：自行控制入库文档集

S3 Storage 支持从 AWS S3 及其他 S3-compatible storage 拉取文档。当前列出的格式为 .md、.mdx、.txt、.docx、.pdf；其他格式会被忽略。Markdown 和纯文本文件另有一千万字符的入库限制。S3 Storage

实际接入需要：

1. 准备只包含目标文档的桶或 prefix。
2. 创建专用凭据，只授予目标范围所需的 List、Read 权限。
3. 在 kapa 添加 S3 Storage，填写桶名、Access key ID、Secret access key 和可选 prefix。
4. 保存，等待文件被发现和处理，检查内容及引用地址。

对 Blog，建议按已发布文章清单导出正文，而不是整体复制仓库。private/、草稿、模板和项目规则不能仅因为扩展名是 .md 就进入公开问答知识库。已有的图片存储桶也不等于文章知识库：连接桶不会让图片自动变成缺失的文章正文。

一种建议的数据流是：

flowchart TB
    articles["Blog 已发布文章清单"] --> export["导出正文<br/>解析链接与组件表达"]
    export --> files["S3 Storage<br/>文档文件与 index.json"]
    files --> ingest["kapa Ingestion"]
    ingest --> retrieve["Retrieval 返回 Chunks"]
    retrieve --> citation["source_url 指向公开文章"]

这里的导出步骤是接入方需要完成的工作，不是 kapa 自动理解 Blog 发布规则的保证。

用 index.json 让存储桶引用指向文章

文件在存储桶中，读者应该打开的却往往是网站文章。S3 Storage 允许通过 index.json 建立两者的映射。

下面是 JSON 结构示例。example.com 是占位域名，需要替换为真实文章的 canonical URL：

[
  {
    "object_key": "published/docs/example.md",
    "source_url": "https://example.com/docs/example/"
  }
]

object_key 使用完整对象键，包括配置的 prefix；它不是本机文件路径。index.json 放在桶根或所选 prefix 下。映射成功后，kapa 可以在引用中展示 source_url。S3 Storage：URL mapping

不要让引用指向读者无法打开的私有对象地址，也不要直接根据 Markdown 文件名猜文章 URL。站点的 slug、路径兼容和重定向规则可能使两者不同。

R2 的边界：支持协议不等于已有专用配置指南

kapa 声明支持 S3-compatible storage，但当前 S3 Storage 页面没有单独列出 R2，公开配置表也未展示自定义 endpoint 字段；官方提示非 AWS 提供方可能需要额外配置并联系支持。因此，R2 是可以评估的候选，不能仅凭协议兼容就宣称已经完成 kapa 与 R2 的联调。S3 Storage：Compatible storage services

采用这条路线前，应确认自定义 endpoint 的配置方式，以及目标桶的文件发现、正文读取和 URL mapping 是否正常。本文没有连接真实 R2 桶；这一限制不影响前述 AWS S3 / S3-compatible 接口能力的介绍。

GitHub Code：省去导出，但要理解发布边界

GitHub Code 支持 .md、.mdx、.txt 等文档，以及多种源代码格式。可以按文件类型和目录选择内容，私有仓库需要适当的只读凭据。GitHub Code

对于公开文档，问题不只是能否读取：仓库可能包含草稿和未发布变更，而引用还可能指向普通读者无权访问的仓库文件。Connector 不能被假定为自动理解站点的 draft、发布排除规则或最终网页 URL。若这些规则复杂，Web Crawling 或经过筛选的导出集更容易控制公开边界。

同样，支持 .mdx 扩展名不意味着会执行其中任意 React 组件。实际导入后应检查组件承载的信息是否仍有文字表达。

Refreshes：源内容变了，多久可以搜到

以上按 2026-09-08 官方文档整理。它们是检查与同步安排，不是端到端可查询时间的 SLA；入库处理和审核也会影响可见时间。Refreshes、File Upload

Web Crawling 可以从 Source 的操作菜单手动 Refresh。超过 45% 的页面发生新增、修改或删除时，更新会转入人工审核，通过后才同步到生产索引。其他 Source 按文档列出的计划刷新，不能假设都有相同的手动 Refresh 功能。

对经常更新的 Blog，这意味着两件事：发布新文章后可以主动刷新 Web Crawling；撤回文章后也要检查索引中的旧内容是否消失。只做前端隐藏，不会改变已经入库的内容。

使用入口：Widget、HTTP API 与 MCP

Website Widget：最短的网页问答接入

先完成知识源索引，再在 Integrations → Add new integration 创建 Website Widget，启用生产和测试域名，复制 Integration ID。官方脚本中的 data-website-id 就是该 Integration ID。Website Widget Quickstart

以下为 HTML 安装片段，需把占位 ID 替换为后台生成值，放入站点的 <head>。本文只展示接入方法，没有将它装到本站：

<script
  async
  src="https://widget.kapa.ai/kapa-widget.bundle.js"
  data-website-id="YOUR_INTEGRATION_ID"
  data-project-name="Blog Docs"
></script>

预期结果是页面出现问答入口，用户可以提问并看到引用。若加载失败，检查域名启用状态与站点 CSP。Widget 默认会进行匿名用户跟踪，接入时还应按网站自身的数据处理约定配置。Website Widget Quickstart

在 Blog 这种内容与站点工程分离的结构中，脚本安装属于站点布局工作，文章内容仓库只维护正文。

Retrieval API：先观察原始结果

The Retrieval endpoint returns relevant Chunks without generating a final answer. top_k limits the number of Chunks, not the number of distinct articles. Retrieval API reference、Tune retrieval size

以下命令适用于 Bash / Zsh，依赖支持 --fail-with-body 的 curl。先通过本地安全配置设置环境变量 KAPA_PROJECT_ID 与 KAPA_API_KEY，并确保 Project 已有完成索引的内容。

curl --fail-with-body \
  "https://api.kapa.ai/query/v1/projects/${KAPA_PROJECT_ID}/retrieval/" \
  -H "X-API-KEY: ${KAPA_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "多个请求之间共享状态，有哪些方案和限制？",
    "top_k": 5,
    "max_chars": 12000,
    "use_pruning": false
  }'

预期得到相关 Chunks 的 JSON 结果，而不是一段生成回答。本示例依据接口文档核对了请求路径、认证头与参数，但没有使用真实 API key 执行远程查询，不提供虚构响应。API authentication

top_k 和 max_chars 都是上限，不是必须填满的目标。当前默认值分别为 15 和 35,000；先观察默认或小范围配置，再根据真实问题调整。Tune retrieval size

若用返回结果制作文章列表，需要自行按来源组织内容，而不是把五个 Chunks 直接当成五篇文章。若交给 Agent 生成回答，还要让回答保留引用，并在证据不足时明确表达不确定性。正确的 Retrieval 不能单独保证后续回答一定正确。

延迟和限流影响 UI 设计

官方给出的 Retrieval 典型延迟是 p50 约 3 秒、p95 约 4.5 秒；开启 Pruning 约增加 0.7 秒。默认团队限流是 Retrieval 每分钟 60 次请求、Documents 每分钟 100 次请求，跨团队内的 Project 和 Integration 计算，超限返回 HTTP 429。HTTP API

这些数字说明它更适合作为提交问题后的查询入口，而不是每输入一个字符就发送请求。自定义网页应由后端保存 API key，处理加载状态和限流；不能把服务凭据直接打包进浏览器代码。

Hosted MCP server：让 Agent 直接获得工具

Hosted MCP server 对外提供与 Retrieval API 相同的检索能力，可选启用 Documents tool 获取更完整的文章。应用不需要为了使用 MCP 再建一份索引。Hosted MCP server

Public 不等于匿名访问。使用 API key 的 MCP 请求也不要照搬 HTTP API 的 X-API-KEY 认证头，两种入口的认证约定不同。后台创建后应复制实际 MCP URL；子域名和认证类型在创建时确定，不能假设日后可以直接修改。Hosted MCP server

对于多个专题，可以通过 Source groups 组织来源并限制入口的查询范围。分组首先是检索组织能力，不应仅凭浏览器传来的分组参数建立敏感内容的访问边界。

用 Blog 验证效果，而不是只看回答是否流畅

首次试用建议选一个公开专题，整理十几个已有明确出处的问题，先看 Retrieval，再看生成回答。下表是建议的评估方法，不是已完成的 kapa 实测结果。

若结果不好，先检查 Source Preview 是否丢了内容，再检查查询范围和返回 Chunks。原始 Chunks 已正确、生成回答却偏离依据时，问题更可能在回答阶段；不要只靠不断增加导入量解决所有问题。

同一批文章也不必一开始同时接入网页、GitHub 和存储桶。建议先使用一种权威来源，便于定位更新和引用问题，再按实际缺口补充其他 Source。

截至整理日期，价格页提供 14 天试用，包含有限用量的一个索引；Growth 和 Enterprise 需要联系销售，页面没有公开固定金额。评估时应同时确认内容规模、请求量和所需入口的报价，不把试用等同于长期免费方案。Pricing

对于 Blog，Web Crawling 适合先验证公开页面的内容与引用；S3 Storage 适合维护经过处理的文档集；File Upload 适合少量补充。Retrieval API 用来验证原始检索效果，Website Widget 用来缩短网页问答接入，Hosted MCP server 用来服务外部 Agent。选择的依据是内容维护成本、引用可达性、实际结果和响应时间，而不是单看支持多少种 Connector。

与 Cloudflare AI Search 对比：直接用会不会更方便

先分清目标：面向读者的问答界面，和面向 Agent 的检索能力，工作量差在不同地方。

kapa 的核心产品体验之一是可直接嵌入的 Website Widget：索引完成后，在站点 <head> 挂一段脚本，就能得到带引用的问答入口，不必自己做搜索结果列表、对话气泡、流式输出和引用展示。Website Widget Quickstart

AI Search 的产品定位是托管的 search primitive：建好 Instance 后，默认交给你的是 search()（返回 chunks）和 chatCompletions()（再生成回答）。读者可见的搜索框、对话页、加载态、引用卡片，通常要在站点工程里自己做，或再接一层官方 UI snippets。AI Search overview · Add search to your website

因此：

• 只要尽快给 Blog 挂上「读者能用的问答」：kapa 前端工作量明显更少。
• 只要给站内 Agent / 后端提供检索，且站点已在 Cloudflare：AI Search 基建工作量通常更少。
• 不要把“账户里建索引更方便”误写成“整条读者体验也更方便”。

完整 AI Search 能力见：Cloudflare AI Search：功能、使用方式与最佳实践。

前端组件：差异最大的一块

AI Search does ship UI snippets (search bar, chat bubble, search modal) that connect to a Public endpoint, so “完全没有前端组件”不准确。它们缩短的是“从零画控件”的时间，并不取消 Public endpoint、CORS、以及与站点设计系统对齐的工作；和 kapa 那种以 Widget 为主交付物的路径仍不是同一量级。UI snippets · Website Widget

flowchart TB
  subgraph readerGoal["目标：读者可问"]
    kapaUI["kapa Website Widget<br/>贴脚本即可问答"]
    aisUI["AI Search<br/>自研 UI 或 UI snippets"]
  end
  subgraph agentGoal["目标：Agent / 后端检索"]
    kapaAPI["kapa Retrieval / MCP"]
    aisAPI["AI Search binding / REST / MCP"]
  end
  readerGoal --> pick1["读者入口：kapa 通常更省"]
  agentGoal --> pick2["已在 Cloudflare：AI Search 通常更省"]

其余能力对照

kapa Connectors · AI Search data sources · Syncing · Limits & pricing

工作量差在哪里（按阶段）

验收时请把 UI 单独算进成本，不要只比“索引能不能建起来”：

1. 读者入口：kapa 以 Widget 可提问且引用可点开为通过；AI Search 以自研页或 UI snippets 能完成同等任务为通过，并计入站点布局、CSP、CORS 与视觉一致性工作。
2. AI Search 本站线：Website + Path filtering + Content selector → search() 抽查；发布后可试 wrangler ai-search jobs create。
3. 不要两边并行当权威索引；短期对比可以，生产只留一条同步路径。

怎么选（给 Blog 的实用结论）

• 要读者马上能问文档：优先 kapa Website Widget。 省下的是一整套搜索 / 聊天前端，而不只是少写几个 API 调用。
• 要站内 Agent、后端检索、R2 / Workers 一体、发布后主动同步：优先 AI Search。 这时你可以暂时没有面向读者的聊天页，工作量主要在 Instance 与 binding。
• 两条都要时： 仍建议只建一套权威索引。若选 AI Search，把“自研或 snippets 对话 UI”单独排期，不要假设建完 Instance 就等于读者体验已上线；若选 kapa，Agent 侧再接 Retrieval / MCP，而不是再复制一份内容到 AI Search。

Public endpoints are unauthenticated by default; only index content that is safe to expose, rate-limit the endpoint, and use Cloudflare Access on a custom domain when you need identity gates. Public endpoint settings

关联阅读

• Cloudflare AI Search：功能、使用方式与最佳实践：Instance、Data source、search() / chatCompletions()、同步与限额的完整说明。
• Agents 文档导航：继续阅读 Agent 工具调用、知识检索和工程实践相关内容。