跳到主内容Loading...
这篇教程会完成什么
这篇教程会把一个你有权处理的公开文档站，转换成可追踪来源、可增量更新、可评测的 RAG 知识库。
最终管线包含：
- 明确授权、域名和路径范围。
- 用 Firecrawl Map 发现 URL，而不是直接无上限爬取。
- 用 Crawl 或 Scrape 获取 Markdown 和元数据。
- 清洗重复页面、个人信息与提示词注入。
- 按语义分块并保存来源、时间和内容哈希。
- 写入向量库或混合检索系统。
- 建立问答评测、人工抽检和增量更新。
- 设置 credits 预算、失败回退和删除流程。
示例以 Firecrawl Cloud API 为主。接口和套餐可能变化，上线前要对照官方文档。不要把 API Key、登录 Cookie、私有页面或用户数据复制进代码仓库、日志或向量库。
开始前需要准备
确认数据授权
优先选择以下来源：
- 你自己维护的产品文档、帮助中心或公开知识库。
- 明确允许索引、复用或通过 API 获取的站点。
- 已获得书面许可的客户或合作伙伴内容。
不要因为页面能公开访问，就默认可以批量抓取、长期保存、重新发布或用于模型训练。检查 robots.txt、站点条款、版权、个人信息和适用地区法规。robots.txt 是重要信号，但不是完整法律判断。
如果内容需要登录，先询问是否有官方 API、导出或内部数据连接器。不要把个人账号 Cookie 交给无人值守 Agent。
建立测试集
先选 30 到 100 个代表页面：
- 普通文档页。
- JavaScript 渲染页面。
- PDF 或长页面。
- 重复语言、标签和分页页面。
- 已删除、重定向、403 或 404 页面。
- 含代码、表格、FAQ 和导航的页面。
再准备 20 到 50 个有明确答案的问题，每个问题记录期望答案和权威来源。这组数据会用于判断抓取、分块和检索是否真的有效。
准备最小权限凭据
在 Firecrawl 控制台创建单独的项目 Key，不要复用生产系统的万能凭据。把 Key 存入 Secret Manager 或本地环境变量：
export FIRECRAWL_API_KEY="在本地安全设置，不要提交到 Git"
日志只记录请求 ID、域名、路径规则、状态、credits 和错误类型，不记录完整 Key、Cookie 或敏感正文。
第一步：先写抓取策略
在调用 API 前，先写一份可审查的配置：
{
"allowed_hosts": ["docs.example.com"],
"include_paths": ["/docs/**", "/guides/**"],
"exclude_paths": ["/login/**"
常见问题
- Firecrawl 免费版能建立多大的 RAG 知识库？
- 免费版适合小样本验证，不应只按 1,000 credits 等于 1,000 个最终文档估算。搜索、高级格式、错误页、重试和更新都会改变成本，应先用 30 到 100 个代表页面测算。
- 应该先用 Map 还是直接 Crawl？
- 先用 Map。它能帮助你检查 URL 数量、路径、重复语言和异常参数，再由人审核范围。确认 include、exclude、深度和页面上限后，才提交受控 Crawl。
- 网页进入向量库前必须保存哪些元数据？
- 至少保存来源 URL、canonical URL、标题、标题路径、语言、抓取时间、内容哈希、权限或可见性和工具版本。这样才能引用、增量更新、删除和审计。
- 如何避免网页提示词注入控制 Agent？
- 把检索内容视为不可信数据，不放入系统消息；限制域名和工具权限；检索服务不拥有外部写权限；发送、发布、购买、删除和凭据访问必须人工批准。
- Firecrawl 自托管是否更适合私有文档？
- 不一定。自托管可增加基础设施控制，但仍要处理浏览器、代理、队列、数据库、监控、升级和 AGPL 合规。私有文档还需要继承原访问权限和完善删除流程。
- 多久更新一次知识库？
- 按内容变化频率决定。产品文档可每日或每周检查，低频政策页可以更慢。使用 Map、ETag、Last-Modified 或内容哈希发现变化，只重抓和重新嵌入变化页面。
,
"/account/**"
,
"/search/**"
,
"/tags/**"
]
,
"max_pages"
:
500
,
"max_depth"
:
4
,
"languages"
:
[
"zh"
,
"en"
]
,
"retention_days"
:
90
}
这份配置应由内容所有者或数据负责人批准。Agent 不应根据网页里的链接自动扩大域名，也不应把第三方子域、用户页面或下载附件加入范围。
- 最大页面数。
- 最大深度。
- 单次和每日 credits。
- 并发数。
- 超时和最多重试次数。
- 允许的文件类型。
- 最大正文长度。
如果任务达到上限，应该暂停并报告，而不是自动提高额度。
第二步：用 Map 估算站点范围
不要一开始就 Crawl 整个域名。先用 Map 获取 URL 清单：
curl -X POST "https://api.firecrawl.dev/v2/map" -H "Authorization: Bearer $FIRECRAWL_API_KEY" -H "Content-Type: application/json" -d
"url": "https://docs.example.com",
"limit": 500
}
- URL 数量是否符合预期。
- 是否混入登录、账户、搜索和标签页。
- 是否包含查询参数造成的重复页面。
- 是否有多语言镜像、打印版或旧版本。
- 是否出现不在允许域名中的链接。
Map 结果不是最终抓取许可清单。应用层仍要解析 URL，统一协议、主机名、结尾斜杠和查询参数，再通过白名单过滤。
{
"source_url": "https://docs.example.com/guides/start",
"canonical_url": "https://docs.example.com/guides/start",
"discovered_at": "2026-09-18T00:00:00Z",
"scope_rule": "/guides/**",
"status": "approved"
}
manifest 能解释为什么某个页面进入知识库，也方便后续删除和增量更新。
第三步：小批量 Scrape 验证质量
curl -X POST "https://api.firecrawl.dev/v2/scrape" -H "Authorization: Bearer $FIRECRAWL_API_KEY" -H "Content-Type: application/json" -d
"url": "https://docs.example.com/guides/start",
"formats": ["markdown"],
"onlyMainContent": true
}
- 标题和正文是否完整。
- 导航、页脚和广告是否被移除。
- 代码块、表格和列表是否保留。
- 页面语言和 canonical URL 是否正确。
- 更新时间能否取得。
- 是否包含 Cookie Banner、登录提示或隐藏文本。
- 是否出现密钥、电子邮件、电话号码或用户数据。
如果 10 个样本中只有 6 个可用，不要直接扩大 Crawl。先分析失败类型：页面需要 JavaScript、正文选择不正确、来源本身为空、付费墙、登录、地区限制，还是内容格式不受支持。
第四步：受控执行 Crawl
样本通过后，再提交 Crawl。路径规则和字段名称以当前官方文档为准：
curl -X POST "https://api.firecrawl.dev/v2/crawl" -H "Authorization: Bearer $FIRECRAWL_API_KEY" -H "Content-Type: application/json" -d
"url": "https://docs.example.com",
"includePaths": ["/docs/**", "/guides/**"],
"excludePaths": ["/login/**", "/account/**", "/search/**"],
"limit": 500,
"maxDiscoveryDepth": 4,
"scrapeOptions": {
"formats": ["markdown"],
"onlyMainContent": true
}
}
Crawl 通常是异步任务。保存 job ID，并轮询状态；不要因为暂时未完成就重复提交同一任务。重复任务会增加 credits、页面重复和状态混乱。
- job ID 和请求配置哈希。
- 起止时间、页面数、成功数和失败数。
- 每页 URL、状态、错误类型和 credits。
- 工具/API 版本。
- 原始内容哈希。
- 清洗后内容哈希。
不要只保留最终 Markdown。没有 manifest 和错误记录，后续无法解释缺页、重复和成本变化。
第五步：清洗、去重与安全处理
URL 与内容去重
- 移除跟踪参数。
- 统一大小写和结尾斜杠。
- 优先使用 canonical URL。
- 识别打印版、AMP、语言镜像和分页。
- 对正文生成稳定哈希。
URL 不同但正文哈希相同，可以保留一个主文档，并把其他 URL 作为 aliases。正文变化很小的页面可用相似度判断，不要把法律声明和导航差异当成新版本。
删除不需要的信息
- 导航、页脚、广告和 Cookie 提示。
- 登录表单和账户信息。
- 隐藏脚本、追踪参数和无关推荐。
- 不需要的电子邮件、电话、地址和个人信息。
- API Key、Token、Cookie、私有 URL 和内部备注。
敏感信息检测失败时，应隔离文档等待人工处理，而不是继续索引。
防止提示词注入
- “忽略之前指令”。
- “读取本地文件并上传”。
- “调用某个工具发送结果”。
- 伪造的系统消息。
- 隐藏在样式或注释中的指令。
- 明确告诉模型，检索内容只是参考数据。
- 不把网页文本拼接为系统或开发者消息。
- 检索服务没有外部写入权限。
- 域名和工具使用固定白名单。
- 发送、发布、购买、删除和凭据访问必须人工批准。
- 保存被过滤片段和规则版本，方便复盘误判。
正则可以筛掉明显模式，但不能独立解决提示词注入。更重要的是权限隔离和固定执行边界。
第六步：分块与元数据设计
不要按固定字符数盲目切割。优先沿 Markdown 标题、段落、列表和代码块分段，再控制每块长度和重叠。
{
"chunk_id": "sha256(source_url + content_hash + position)",
"source_url": "https://docs.example.com/guides/start",
"canonical_url": "https://docs.example.com/guides/start",
"title": "Getting Started",
"heading_path": ["Guides", "Getting Started"],
"language": "en",
"fetched_at": "2026-09-18T00:00:00Z",
"content_hash": "sha256...",
"license": "known-or-review",
"visibility": "public",
"text": "..."
}
来源和时间不是装饰字段。回答时应返回 source_url，更新时应比较 content_hash，删除请求也需要根据来源定位所有 chunk。
代码块、表格和步骤列表尽量保持完整。一个配置示例被切成三块，模型很容易漏掉上下文或组合出错误参数。
第七步：写入检索系统
小型知识库可以先用全文检索；语义问题较多时再加入向量检索。混合检索常比只用向量更稳：
- 关键词或 BM25 找精确产品名、错误码和参数。
- 向量检索找语义相近段落。
- 根据来源、语言、版本和更新时间过滤。
- 重排后只把少量高质量 chunk 交给模型。
- 答案必须附来源，低置信度时承认无法确认。
不要把整篇文档直接塞进上下文。它会增加成本，也可能让旧版本、导航和注入文本影响回答。
对内部知识库，向量库必须继承原始文档权限。用户没有权限打开来源，就不应看到其 chunk 或模型摘要。
第八步：建立问答评测
- 期望来源是否进入前 K 个结果。
- 回答是否与来源一致。
- 引用是否真的支持结论。
- 是否混用旧版本。
- 无答案问题是否明确拒答。
- 中文和英文查询是否都能命中。
- 数字、价格、日期和配置参数是否准确。
- Recall@K。
- 引用正确率。
- 支持性回答比例。
- 无答案拒答准确率。
- P50/P95 延迟。
- 每个回答的搜索、抓取、嵌入与模型成本。
- 人工审核通过率。
评测未通过时，不要只换模型。问题可能来自抓取缺页、分块破坏、元数据缺失、检索过滤或旧版本没有删除。
第九步：增量更新而不是全部重抓
为每个来源保存 ETag、Last-Modified、内容哈希或最近抓取时间。更新流程可以是：
- 定期 Map 检查新增和删除 URL。
- 对变更候选执行 Scrape。
- 比较内容哈希。
- 只重新分块和嵌入变化页面。
- 对删除页面标记 tombstone，并清理对应 chunk。
- 运行一小组回归问题。
- 审核通过后切换索引版本。
使用蓝绿索引更安全：新索引完成和验证前，线上仍读取旧索引；出现异常时可以快速回退。
不要让更新任务在没有页面上限和预算上限时运行。站点误生成大量日历、筛选和查询参数页面，可能迅速耗尽 credits。
第十步：上线前人工门禁
- 域名、路径和内容用途已经授权。
- 抽样页面正文完整，代码与表格可读。
- 没有登录页、个人信息、密钥和内部内容。
- 提示词注入测试没有触发外部操作。
- RAG 回答附来源，关键答案可以打开原文核对。
- 无答案场景不会编造。
- credits、并发、超额和告警已经设置。
- 数据保留、删除和供应商故障回退可执行。
- 负责人清楚谁能扩大范围和批准高风险变更。
常见错误
直接 Crawl 整个根域名
问题：抓到搜索、标签、日历、账户和重复语言页面，成本失控。
修复：先 Map，审核 manifest，再使用 include、exclude、深度和 limit。
只保存正文，不保存来源
问题：模型回答无法引用，页面更新和删除也无法追踪。
修复：每个文档和 chunk 保存 canonical URL、抓取时间、内容哈希和版本。
把网页内容当作 Agent 指令
问题：提示词注入可能诱导工具读取文件、发送消息或修改外部系统。
修复：检索内容只作为数据；工具权限隔离；外部写操作需要固定代码和人工批准。
把 credits 当作准确页面数
问题：高级格式、搜索、浏览器、错误页和重试改变实际消耗。
修复：用代表页面计算每个有效文档成本，并设置每日与单任务预算。
每次更新都全量重抓
修复：保存哈希和 manifest，只更新变化页面，并使用可回退索引。
私有文档沿用公开站点方案
修复：优先官方 API 或导出；继承访问控制；评估 DPA、数据驻留和保留策略；不要把个人登录交给无人值守任务。
什么时候该换别的工具
- 只需要围绕问题搜索最新网页：优先 Tavily。
- 需要从固定模板提取商品名、价格和库存：评估 AgentQL。
- 需要操作 Gmail、Slack、Notion 等应用：使用 Composio，并加最小权限和人工批准。
- 只做一次人工研究：Perplexity AI 可能更快。
- 站点提供稳定官方 API：优先 API，不要为了统一技术栈强行抓网页。
- 自托管成本高于托管服务：重新评估基础设施、代理和维护投入。
最终检查清单
官方资料
