Crawl4AI Docker 部署的 /ask 文档上下文系统c4ai-doc-context.md 如何为 AI 问答端点提供检索基础【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4aideploy/docker/c4ai-doc-context.md是 Crawl4AI Docker 服务端内置的文档上下文聚合文件它将仓库中 31 篇官方文档core / advanced / extraction 三大板块按## File: 路径分节拼接为单一 Markdown 资产供 server.py 中的/ask端点读取再通过 BM25 打分与上下文邻域扩展把最相关的文档片段返回给 AI 助手或 LLM 客户端。读完后你将理解该上下文文件的组织方式与知识覆盖面、/ask端点的完整请求参数与返回结构、以及 BM25 分块检索管线在源码中的具体实现。1. 文件定位一个给机器读的知识底座该文件头部声明如下# Crawl4AI Doc Context Generated on 2025-04-21它不是面向人类阅读的教程而是一份预生成的检索语料库。其结构遵循固定模板每篇源文档以二级标题作为分节锚点文档正文包在 md 围栏内——## File: docs/md_v2/core/browser-crawler-config.md md # Browser, Crawler LLM Configuration (Quick Overview) ...该文档的完整 Markdown 内容这个格式不是随意约定的它直接决定了 /ask 端点的分块行为见第 5 节[server.py](https://link.gitcode.com/i/34c6997d7214b2a3a8f77ac23913b15f) 中的 chunk_doc_sections() 正是按 Markdown 标题行来切分检索单元的。 与它配套的是同一目录下的 [c4ai-code-context.md](https://link.gitcode.com/i/bb605ab960db40d8f3adcb8d4da71c20)约 1.16 万行两者共同构成 /ask 端点可返回的两类上下文。 ## 2. 知识地图31 个文档分节的完整覆盖 该文件聚合了 [docs/md_v2](https://link.gitcode.com/i/6591c7000caa73e70907a5c596d96d1a) 下三个板块的全部核心文档构成一套覆盖 Crawl4AI 主要能力面的知识库 ### 2.1 core 板块16 篇——安装与核心 API | 分节 | 主题与关键内容 | |---|---| | [ask-ai.md](https://link.gitcode.com/i/93eebe9d48d73162cffdd31f92fb8d24) | 特殊分节嵌入 Ask AI 助手的 iframe 与自适应高度脚本片段 | | [browser-crawler-config.md](https://link.gitcode.com/i/a8a0aa0e1793adab80b7e7e7906932d1) | BrowserConfigbrowser_type、headless、proxy_config、viewport、text_mode 等、CrawlerRunConfigword_count_threshold、js_code、wait_for、cache_mode 等与 LLMConfigprovider、api_token、base_url三大配置类的核心字段速览含 clone() 派生用法与完整组合示例 | | [cache-modes.md](https://link.gitcode.com/i/fc228d7c6eff87985567c0db8601f82e) | v0.5.0 起以 CacheMode 枚举ENABLED / DISABLED / READ_ONLY / WRITE_ONLY / BYPASS取代旧布尔标志bypass_cache、no_cache_read 等附新旧代码迁移对照表 | | [cli.md](https://link.gitcode.com/i/19fa4a3b81224c06c61beaac1baaf33d) | crwl 命令行工具-B/-C 浏览器与爬虫 YAML 配置、-e/-s 抽取配置与 JSON Schema、-q LLM 问答、-f 内容过滤BM25/Pruning、-o 输出格式all/json/markdown/markdown-fit与最佳实践 | | [content-selection.md](https://link.gitcode.com/i/0168c937707c02be2c8b724c3ec87deb) | css_selector 与 target_elements 两种选择方式的区别、excluded_tags/排除域/排除图片等过滤参数、iframe 处理、JsonCssExtractionStrategy 与 LLMExtractionStrategy 结合示例、LXML 抓取策略文档称大文档下可快 10-20 倍且标注为实验性 | | [crawler-result.md](https://link.gitcode.com/i/665b6ef66c80d3710ab42240e796cc7c) | CrawlResult 全字段表html/cleaned_html/markdownMarkdownGenerationResultraw_markdown、markdown_with_citations、fit_markdown/extracted_content/links/media/screenshot/pdf/mhtml/ssl_certificate 等 | | [deep-crawling.md](https://link.gitcode.com/i/ef67d7efb26be0511f87c5038ccb7d7a) | BFS/DFS/BestFirst 三种深度策略、流式与非流式结果、FilterChainURLPattern/Domain/ContentType/SEO/ContentRelevance 过滤器、KeywordRelevanceScorer 等评分器、max_pages 与 score_threshold 限幅 | | [docker-deployment.md](https://link.gitcode.com/i/6c6908579ffac78b80146c1226d2ce4f) | Docker 镜像构建build-args 表PYTHON_VERSION、INSTALL_TYPE、ENABLE_GPU、.llm.env 配置、Crawl4aiDockerClient Python SDK、REST API 的 type/params 配置语法与嵌套示例、config.yml 完整结构与 JWT 认证流程、生产/开发/高流量三套配置建议 | | [fit-markdown.md](https://link.gitcode.com/i/6492c7319a7af32436fcc9e500345d7a) | PruningContentFilterthreshold、threshold_type、min_word_threshold与 BM25ContentFilteruser_query、bm25_threshold的用法与调参、自定义 RelevantContentFilter 子类步骤、多层过滤管线excluded_tags → 内容过滤 → fit_markdown | | [installation.md](https://link.gitcode.com/i/b56b9d5edc85b1ce1d41660237fa2b34) | pip install crawl4ai crawl4ai-setup crawl4ai-doctor 诊断流程、torch/transformer/all 可选依赖、模型预下载命令 | | [link-media.md](https://link.gitcode.com/i/d948ccf4fa960443e2281cb996a892e3) | result.links 内外部链接结构href/text/title/base_domain、域过滤参数、result.media 的 images/videos/audio/tables 结构与字段、table_score_threshold 表格识别调参、MHTML 快照示例 | | [local-files.md](https://link.gitcode.com/i/f4f66fc931cb55e6cb39dbd14fe7cf49) | 三种前缀输入http(s):// 实时抓取、file:// 本地 HTML 文件、raw: 原始 HTML 字符串附三步一致性验证完整示例 | | [markdown-generation.md](https://link.gitcode.com/i/b74fe8eb4cf02a20ef6605c5230cab10) | Markdown 生成策略配置DefaultMarkdownGenerator、citations、body_width 等选项 | | [page-interaction.md](https://link.gitcode.com/i/f15f99e1508640a8ea6172ac0c55f60f) | 页面交互点击、滚动、JS 注入、等待条件等动态页面操作 | | [quickstart.md](https://link.gitcode.com/i/ca7ce4005b2c3e96b05f9fc12bd7b8d3) | 快速上手最小示例 | | [simple-crawling.md](https://link.gitcode.com/i/2ad505e937eb0e5eba07bbbbd58b83d5) | 单页抓取基础流程 | ### 2.2 advanced 板块11 篇——进阶能力 覆盖[advanced-features](https://link.gitcode.com/i/1d7ad11be5ee12470d2d110adfdb431c)、[crawl-dispatcher](https://link.gitcode.com/i/6db241eb0430f2955a6785505686afd0)分发器、[file-downloading](https://link.gitcode.com/i/d2e58cc5ebc5aa29fb783e609f321b3d)文件下载、[hooks-auth](https://link.gitcode.com/i/1703d903beb2665967398c8321ac2c7f)Hooks 与登录态注入、[identity-based-crawling](https://link.gitcode.com/i/97b9548c7420c6b1b95bc4731754f0bc)身份化浏览、[lazy-loading](https://link.gitcode.com/i/abeee9cc0fc79a92509e23f0548c2b45)、[multi-url-crawling](https://link.gitcode.com/i/7a867611234b26b604f893e33c2866e8)arun_many、[network-console-capture](https://link.gitcode.com/i/2e73c038afc38fe083e8b4e6774b97d8)网络请求与控制台捕获、[proxy-security](https://link.gitcode.com/i/d25900378999f2e412fbd8f77a11f3c5)、[session-management](https://link.gitcode.com/i/9986e76547fe502f1861bbb8f485db47)会话复用与持久化、[ssl-certificate](https://link.gitcode.com/i/eda6ec5f9b570c3a6b8608668e8613a3)证书抓取。 ### 2.3 extraction 板块4 篇——抽取与分块策略 [chunking](https://link.gitcode.com/i/e769a438b6f12fb4247bbb0250b063ad)分块策略、[clustering-strategies](https://link.gitcode.com/i/38aafc9c8ce486c4a499ada5b63a8287)聚类/去重策略、[llm-strategies](https://link.gitcode.com/i/4a05201440294987035145172dc8b30f)LLM 抽取、[no-llm-strategies](https://link.gitcode.com/i/71c800d12ec71b65d587215bd263eb0a)JSON-CSS 等无 LLM 抽取。 这套语料的价值在于AI 助手在回答Crawl4AI 如何做 X这类问题时所需的配置参数名、类名、枚举值和代码范式全部包含在这一个文件中无需再访问网络文档站。 ## 3. /ask 端点上下文的唯一消费入口 服务端在 [server.py](https://link.gitcode.com/i/05e6ee7e75a66bcd6c80a07dbfad2bc2) 中定义了对应的 HTTP 与 MCP 双重入口 python app.get(/ask) limiter.limit(config[rate_limiting][default_limit]) mcp_tool(ask) async def get_context( request: Request, _td: Dict Depends(token_dep), context_type: str Query(all, regex^(code|doc|all)$), query: Optional[str] Query(None, descriptionsearch query to filter chunks), score_ratio: float Query(0.5, ge0.0, le1.0, descriptionmin score as fraction of max_score), max_results: int Query(20, ge1, descriptionabsolute cap on returned chunks), ):几个源码级事实值得注意双协议暴露app.get(/ask)与mcp_tool(ask)叠加意味着同一函数既可通过 HTTP GET 调用也可通过 MCP 协议被 AI 客户端直接当工具调用attach_mcp()server.py 末尾调用实现位于 mcp_bridge.py还会额外挂载/mcp/ws、/mcp/sse、/mcp/schema端点。鉴权与限流Depends(token_dep)表明当 config.yml 中security.jwt_enabled为true时需携带 Bearer Token/ask与/crawl等端点一致limiter.limit应用rate_limiting.default_limit限流。参数语义context_typecode代码上下文/doc文档上下文即本文件/all默认两者都返回query可选的 BM25 检索词score_ratio默认 0.5命中分数下限取本次最高分 × 该比例是相对阈值而非绝对分max_results默认 20返回分片数的硬上限。端点 docstring 本身也给出了一条明确的最佳实践原话大意面向 AI 助手提问时务必提供query过滤上下文否则响应体将非常长。这一点在实现中也得到了印证——不传query时端点直接整文件返回# if no query, just return raw contexts if not query: if context_type code: return JSONResponse({code_context: code_content}) if context_type doc: return JSONResponse({doc_context: doc_content}) return JSONResponse({code_context: code_content, doc_context: doc_content})两个文件路径均通过os.path.dirname(__file__)相对服务端代码目录解析若任一文件缺失会抛出 404Context files not found。这也解释了为什么这两个 .md 文件必须随 Docker 镜像一同构建进容器。4. 文档检索管线标题分块 BM25 邻域扩展带query时文档上下文走如下管线server.py# doc BM25 over markdown sections if context_type in (doc, all): sections chunk_doc_sections(doc_content) bm25d BM25Okapi([sec.split() for sec in sections]) scores_d bm25d.get_scores(tokens) max_sd float(scores_d.max()) if scores_d.size 0 else 0.0 cutoff_d max_sd * score_ratio idxs [i for i, s in enumerate(scores_d) if s cutoff_d] neighbors set(i for idx in idxs for i in (idx-1, idx, idx1)) valid [i for i in sorted(neighbors) if 0 i len(sections)] valid valid[:max_results] results[doc_results] [ {text: sections[i], score: scores_d[i]} for i in valid ]逐段拆解这套检索逻辑分块粒度由文档格式决定。chunk_doc_sections()server.py逐行扫描凡匹配^#{1,6}\s任意 1–6 级标题的行即切断当前块、开启新块def chunk_doc_sections(doc: str) - List[str]: lines doc.splitlines(keependsTrue) sections [] current: List[str] [] for line in lines: if re.match(r^#{1,6}\s, line): if current: sections.append(.join(current)) current [line] else: current.append(line) if current: sections.append(.join(current)) return sections因此c4ai-doc-context.md被切分为三层粒度## File:大节标题行本身构成一个微型块其下的#/##/###子标题各自开启新块。BM25 是在这些细粒度块上打分而非在整篇文档上打分这是该端点能定位到具体小节的关键。打分与相对截断。使用rank_bm25的BM25Okapi以query.split()的空白分词为检索词截断线cutoff_d 最高分 × score_ratio。score_ratio0.5意味着只要达到本轮最佳块一半相关度的块都会被保留——对多义词查询这相当宽容调高该值如 0.7、0.8可得到更严格的相关性过滤。邻域扩展。命中块的前后各一个块idx-1, idx, idx1一并纳入再按块序号排序并截断到max_results。这一设计弥补了答案跨小节的场景若命中某文档的参数表小节其紧邻的示例代码小节会自动伴随返回避免返回割裂的半截上下文。返回结构。最终 JSON 按context_type携带doc_results和/或code_results{ doc_results: [ {text: ## 2.1 Using target_elements\n...块原文, score: 3.42}, {text: ..., score: 2.91} ] }作为对照代码上下文c4ai-code-context.md走另一条分块管线chunk_code_functions()server.py用正则匹配## File:头与 py 围栏ast.parse后按顶层FunctionDef/AsyncFunctionDef/ClassDef逐函数、逐类切片保证 AI 拿到的代码块是完整、可解析的单元而不是任意行窗口。两条管线共享同一套 BM25 相对截断逻辑但代码管线不做邻域扩展。5. 实战调用以下示例假设容器按 docker-deployment 所述以docker run -d -p 8000:8000 --name crawl4ai crawl4ai启动未启用 JWT启用后所有请求需加Authorization: Bearer token头。5.1 无 query拉取全量文档上下文curl http://localhost:8000/ask?context_typedoc返回{doc_context: 完整 8900 行 Markdown}。适合一次性灌入支持库问答的 RAG 系统但响应体很大端点 docstring 明确建议避免在无 query 时频繁调用。5.2 带 queryBM25 过滤检索curl http://localhost:8000/ask?context_typedocquerydeepcrawlfilterscorescore_ratio0.6max_results5检索词按空白分词deep crawl filter score 会被拆为 4 个词参与 BM25 打分score_ratio0.6使仅保留达到本轮最高分 60% 以上的块max_results5将返回块数压到最小适配有 token 预算限制的助手。5.3 组合代码与文档上下文curl http://localhost:8000/ask?context_typeallqueryCacheModecontext_typeall时同时返回code_resultsAST 切片与doc_results标题切片可让 LLM 在生成代码时同时参考实现与文档。5.4 与 MCP 集成AI 客户端任何支持 MCP 的工具可直接把ask注册为工具调用也可通过 mcp_bridge.py 挂载的 SSE/WebSocket 端点/mcp/sse、/mcp/ws长连接接入。对 Agent 而言向/ask提问 → 拿到带相关度分数的文档块 → 据此生成 Crawl4AI 代码是一条无需额外搭建 RAG 基础设施的现成路径。6. 使用建议与限制query 是首选姿势。全量返回仅适合离线构建索引在线问答场景请始终携带query并用max_results控制返回块数控制喂给 LLM 的 token 量。score_ratio是相关度旋钮。默认 0.5 偏宽松邻域扩展会再带入相邻块查询语义单一时可上调以收窄结果查询是多领域组合时保持默认更稳。分块粒度依赖标题结构。该文件由文档生成而来若将来重新生成上下文文件请保持## File:与标题行结构不变否则chunk_doc_sections()的分块与chunk_code_functions()对代码文件的正则解析## File: py 围栏都会退化。语料时效以生成时间为准。文件头标注Generated on 2025-04-21其中收录的参数名与默认值对应该时点的文档如BrowserConfig、CacheMode枚举、LLM provider 列表。若库版本演进较快建议以仓库当前 docs/md_v2 源文档与 参数参考 为准并用/ask?query参数名交叉核对上下文文件中的对应小节。安全边界。/ask端点受与爬虫端点相同的 JWT 与限流保护见 config.yml 的security与rate_limiting段由于返回内容是只读语料不涉及爬取动作但生产环境仍建议将其纳入统一鉴权避免成为未受限的信息暴露面。7. 小结c4ai-doc-context.md 是 Crawl4AI Docker 部署面向 AI 的文档侧记忆以## File:分节聚合 31 篇官方文档与 1.16 万行的 c4ai-code-context.md 代码侧语料配对由 server.py 的/ask端点统一消费。其检索管线——标题行分块、BM25Okapi 打分、相对最高分截断、命中块 ±1 邻域扩展、max_results硬上限——全部在约 40 行源码中可验证且同一函数通过mcp_tool直接暴露为 MCP 工具。理解这套机制你既能把容器化的 Crawl4AI 服务变成任意 LLM 应用的即插即用知识库也能照此思路为自己的库构建文档上下文 代码上下文 BM25 端点的 AI 友好 API。【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考