Daft 接入 Common Crawl 完整指南s3 / hf / http 三源选择、参数详解与 WARC 解析实现【免费下载链接】DaftHigh-performance data engine for AI and multimodal workloads. Process images, audio, video, and structured data at any scale项目地址: https://gitcode.com/GitHub_Trending/da/DaftCommon Crawl 是规模最大的开放网页数据集之一也是生成式 AI 预训练文本的重要来源。Daft 通过daft.datasets.common_crawl()提供了一套简洁、可并行且可控成本的数据接入层本文基于 Common Crawl 文档 与 Python 实现、WARC 读取器、Rust 解析内核 逐节展开带你掌握三种数据源的选型与鉴权、全部参数crawl/segment/content/num_files/source/io_config的取值行为、标准 DataFrame 列结构以及内容类型统计、文本抽取等可直接运行的实战示例。读完你可以独立完成从“拉取 1 个文件做调试”到“全量 crawl 喂给语言模型流水线”的完整链路。注意这些 API 目前处于 beta 阶段可能随 Common Crawl 数据集的演进而变化原文档 Warning 明确标注。in_aws参数已弃用并将在v0.9.0移除请改用sources3。数据集与 API 概览Common Crawl 包含横跨 18 年、超过 2500 亿个网页的爬取数据。自 2020 年起它成为生成式 AI 的关键训练语料——据 Mozilla 基金会研究当前形态的生成式 AI “很可能没有 Common Crawl 就无法实现”。Daft 的接入入口是 daft.datasets.common_crawl其完整签名为def common_crawl( crawl: str, # 爬取批次 ID如 CC-MAIN-2025-33 segment: str | None None, # 指定 crawl 内的某个 segment content: Literal[raw, text, metadata, warc, wet, wat] raw, num_files: int | None None, # 限制处理文件数 io_config: IOConfig | None None, # 存储访问配置 *, in_aws: bool False, # 已弃用等价于 sources3 source: Literal[s3, hf, http] | None None, ) - DataFrame从 源码 看该函数的工作流程是两段式的先调用_get_common_crawl_paths()下载并解析该 crawl 的manifest 清单文件即{crawl}/warc.paths.gz/wet.paths.gz/wat.paths.gz一行一个文件相对路径再按segment过滤、按num_files截断后把绝对路径列表交给 daft.read_warc 构建 DataFrame。也就是说common_crawl()是“清单解析 WARC 读取”的封装最终产物是一个可直接做列运算、过滤、聚合的 DataFrame。数据源选择AWS S3 / HuggingFace Buckets / HTTPS接入方式取决于传给daft.datasets.common_crawl的参数方式URL Scheme适用场景是否需要凭证注意事项AWS S3s3://commoncrawl/...AWS 内部us-east-1是离开 AWS us-east-1 会产生数据传输费HuggingFace Bucketshf://buckets/commoncrawl/commoncrawl/...跨区域、AWS 外部、成本最低否可选建议提供仅 2026 年及之后的 crawl 可用HTTPShttps://data.commoncrawl.org/...无凭证时的兜底否最慢的选项选择规则与 文档 及 源码_get_mainfest_path一致传in_awsTrue或sources3→ 从 AWS S3 读取传sourcehf或sourceNone且 crawl ID 为 2026 及之后 → 从官方 HuggingFace bucket 读取其余情况 → 从 HTTPS 端点读取。源码中有一个值得注意的自动降级逻辑当sourceNone默认时Daft 先尝试 HuggingFace 的清单路径若该 crawl 在 HF 上不存在FileNotFoundError会自动回退到sourcehttp重读一次。但如果显式指定了sourcehf且找不到则会直接抛出带明确提示的FileNotFoundError“Could not find the crawl ... from the HuggingFace source”。这一行为在 mock 测试 中被显式模拟和验证。警告in_aws已弃用将在v0.9.0移除请改用sources3。若同时设置in_aws和sourcein_aws会优先生效并触发 deprecation 警告见 common_crawl.py#L183-L193。从 AWS 读取 Common CrawlCommon Crawl 数据托管在 AWS Open Data Sets Sponsorships 计划下免费开放。但直接从 S3 下载时需要 AWS 身份认证在 AWS 外部访问则不需要 AWS 账号见 HTTP/HF 两种替代源。关键规则所有 Common Crawl 数据都存放在us-east-1区域强烈建议在同区域的 AWS 服务内访问——连接更快且避免跨区数据传输的出向流量费用。使用daft.datasets.common_crawl在 AWS 云内访问数据时必须传in_awsTrue或sources3否则 Daft 会走非 S3 路径。鉴权方式一AWS 环境自动发现如果环境中已配置 AWS 凭证Daft 会自动检测并使用优先级顺序为AWS 环境变量AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN共享的 AWS CLI / SSO 凭证文件~/.aws/config、~/.aws/credentialsEC2、ECS、EKS 等 AWS 服务挂载的 IAM 角色。这是最省心的方式在 us-east-1 的 EC2/ECI 上跑 ETL 任务时通常无需任何额外配置。鉴权方式二显式配置 IOConfigimport daft from daft.io import IOConfig, S3Config io_config IOConfig( s3S3Config( key_idyour_access_key, access_keyyour_secret_key, session_tokenyour_session_token, region_nameus-east-1, # 数据所在地务必设为 us-east-1 ) ) # 读取 Common Crawl 数据集时传入 io_config daft.datasets.common_crawl(CC-MAIN-2025-33, io_configio_config, in_awsTrue) # 注意在 AWS 云内访问时必须提供 in_awsTrue新代码请写 sources3从 mock 测试 可以确认io_config会原样透传给底层的read_warc同时也被用于清单文件的下载即鉴权配置对“读清单”和“读数据”两个阶段都生效。警告在 AWS 外部使用 S3 源会产生出向流量egress费用此时建议改用 HuggingFace 或 HTTP 源。从 HuggingFace Buckets 读取运行在AWS 外部时推荐优先使用 Hugging Face Buckets 接口——它是可及性最高、成本最低的选项。当 crawl 在官方 HuggingFace Common Crawl bucket 中可用、或显式设置sourcehf时Daft 会自动从该 bucket 读取。目前仅 2026 年及之后的 crawl 在 HF 上提供。import daft daft.datasets.common_crawl(CC-MAIN-2026-25, sourcehf)此外也可以绕过common_crawl()封装直接用daft.read_warc访问 WARC 文件支持通配符 globimport daft # 读取单个 WARC 文件HF Buckets 上的固定路径 daft.read_warc(hf://buckets/commoncrawl/commoncrawl/crawl-data/CC-MAIN-2026-17/segments/1775805908305.14/warc/CC-MAIN-20260410081153-20260410111153-00000.warc.gz) # 按 glob 模式批量读取某 segment 下的全部 WARC 文件 daft.read_warc(hf://buckets/commoncrawl/commoncrawl/crawl-data/CC-MAIN-2026-17/segments/*/warc/*.warc.gz)HuggingFace 鉴权公开数据本身不需要认证但匿名访问可能遭遇更严格的限流。为获得最佳访问体验建议通过IOConfig传入 tokenfrom daft.io import IOConfig daft.read_warc( hf://buckets/commoncrawl/commoncrawl/crawl-data/CC-MAIN-2025-33/segments/..., io_configIOConfig(hfdaft.io.HuggingFaceConfig(tokenhf_xxxxxxxxxxxxxxxxxxxx)) )也可以先用hf auth login登录Daft 会自动拾取本地 token。从 HTTP 读取兜底方案HTTP 端点作为最后兜底同样受支持。它是三者中最慢的选项不建议用于生产负载但适合测试与开发import daft # 使用 HTTPS 兜底 daft.datasets.common_crawl(CC-MAIN-2025-33, sourcehttp)从实现看HTTP 源的清单地址形如https://data.commoncrawl.org/crawl-data/{crawl}/{file_type}.paths.gz解析出的文件路径再以https://data.commoncrawl.org/为前缀拼出完整 URL见 _get_mainfest_path。Quickstart加载一个采样数据最简单的入门方式是加载极小样本并预览import daft daft.datasets.common_crawl(CC-MAIN-2025-33, num_files1).show()num_files1让 Daft 只处理 manifest 中的第一个 WARC 文件。输出是一个 8 列的表格首行为warcinfo记录含isPartOf: CC-MAIN-2025-33等元信息随后是成对出现的request/response/metadata记录——这正是 WARC 格式的典型结构每次抓取对应一条请求、一条响应正文为 HTML/文本等和 Common Crawl 附带的 metadata如fetchTimeMs、charset-detected等。文档中给出的真实输出节选│ WARC-Record-ID │ WARC-Target-URI │ WARC-Type │ WARC-Date │ Content-Length │ ... │ warc_content │ warc_headers │ 526c37b2-f535-4015… │ None │ warcinfo │ 2025-08-02 22:09:07 UTC │ 489 │ ... │ bisPartOf: CC-MAIN-2025-33\r… │ {Content-Type:application/… │ f99237da-09e9-4bf0… │ http://0014housingrental.shop…│ request │ 2025-08-02 23:15:49 UTC │ 308 │ ... │ bGET / HTTP/1.1\r\nUser-Agen… │ ... │ 77dac6f5-296e-4bdc… │ http://0014housingrental.shop…│ response │ 2025-08-02 23:15:49 UTC │ 1751 │ text/html │ ... │ bHTTP/1.1 200 OK\r\nDate: Sa… │ ... │ b09ed72d-7556-4d17… │ http://0014housingrental.shop…│ metadata │ 2025-08-02 23:15:49 UTC │ 94 │ ... │ bfetchTimeMs: 4\r\ncharset-d… │ ...加载三种内容类型WARC / WET / WATCommon Crawl 提供三种内容形态通过content参数选择参数到文件类型的映射见源码原始 Web ARChiveWARC文件默认——包含完整 HTTP 响应头与正文# 原始 WARC 数据默认 daft.datasets.common_crawl(CC-MAIN-2025-33, contentraw) # 等价写法 daft.datasets.common_crawl(CC-MAIN-2025-33, contentwarc)抽取文本即 WET 文件——从网页抽取出的纯文本内容# 抽取的文本内容 daft.datasets.common_crawl(CC-MAIN-2025-33, contenttext) # 等价写法 daft.datasets.common_crawl(CC-MAIN-2025-33, contentwet)元数据即 WAT 文件——不含正文的页面元信息# 仅元数据 daft.datasets.common_crawl(CC-MAIN-2025-33, contentmetadata) # 等价写法 daft.datasets.common_crawl(CC-MAIN-2025-33, contentwat)参数语义是raw/warc、text/wet、metadata/wat两两等价传入其他值会抛出Invalid content type的ValueError有对应单元测试覆盖。从清单路径看content实际决定了下载的是{crawl}/warc.paths.gz、{crawl}/wet.paths.gz还是{crawl}/wat.paths.gz因此选错 content 类型是控制数据量与成本的关键旋钮——做 LLM 文本语料准备时用text做流量分析/URL 挖掘时用metadata体积都远小于原始 WARC。加载数据子集num_files 与 segment限制文件数快速测试/开发时很有用# 只处理 1 个 crawl 文件用于测试 daft.datasets.common_crawl(CC-MAIN-2025-33, num_files1)实现上就是清单 DataFrame 上的.limit(num_files)注意num_files必须为正整数0或负数会抛出ValueError(num_files must be a positive integer)见 源码 与 测试。指定 segment每个 crawl 被切分为 100 个 segment可以定向读取某一个daft.datasets.common_crawl(CC-MAIN-2025-33, segment1754151279521.11)segment 过滤在 源码 中是对清单路径列做contains(segment)谓词过滤segment与num_files可以组合使用先按 segment 过滤再 limit测试用例 验证了二者组合后恰好得到 1 个文件且全部来自指定 segment。数据 Schemacommon_crawl()返回的 DataFrame 包含以下关键列与 read_warc 源码中声明的 schema 一致列类型说明WARC-Record-IDUUID/String每条 WARC 记录的唯一标识WARC-Target-URIString被抓取的 URLwarcinfo记录中为 NoneWARC-TypeString记录类型response、request、warcinfo 等WARC-DateTimestamp(ns, Etc/UTC)页面被爬取的时间Content-LengthInt64记录 payload 字节长度WARC-Identified-Payload-TypeString内容的 MIME 类型warc_contentBinary实际内容HTML、文本等warc_headersString该 WARC 记录的全部头信息JSON 字符串几个源码级细节可以加深理解read_warc的文档明确列出必选元数据列、可选列与warc_content/warc_headers两列内容列并在扫描构建时设置infer_schemaFalse即用上述静态 schema 而非运行时推断保证跨文件类型稳定Rust 端解析器 daft-warc 中定义了完整的WarcType枚举warcinfo、response、resource、request、metadata、revisit、conversion、continuation未知类型以FutureType透传并逐行解析Content-Length、WARC-Record-IDUUID、WARC-Target-URI、WARC-Date等头字段内存估算侧daft-scan 的内存估算逻辑 为 WARC 行采用了经验平均列大小warc_content约 27282 字节、warc_headers约 350 字节。从源码结构看这说明读取 WARC 时单行体积明显大于普通结构化数据在大规模处理时更应善用num_files/segment控制并发数据量。关于 WARC 文件格式的完整规范可参考文档中链接的 WARC Specification外部规范此处不附链接。实战示例示例一分析内容类型分布统计一个 crawl 中出现的 MIME 类型频率( daft.datasets.common_crawl(CC-MAIN-2025-33, num_files1) .select(daft.col(WARC-Identified-Payload-Type)) .groupby(WARC-Identified-Payload-Type) .agg(daft.col(WARC-Identified-Payload-Type).count().alias(count)) .sort(count, descTrue) .show() )文档中给出的真实输出单个文件样本│ WARC-Identified-Payload-Type │ count │ │ text/html │ 21907 │ │ application/xhtmlxml │ 2063 │ │ application/pdf │ 143 │ │ application/atomxml │ 28 │ │ text/plain │ 23 │ │ application/rssxml │ 14 │ │ application/xml │ 14 │ │ text/calendar │ 7 │这类统计同样适用于按WARC-Type过滤——例如只看response记录、或按WARC-Date时间范围裁剪都是普通的列表达式运算。示例二为语言模型抽取文本Common Crawl WARC 文件中的内容为 UTF-8 编码。使用 Daft 的 try_decode 函数可以安全地把warc_content字节列解码为文本列非法序列返回 null 而非报错非常适合做训练语料准备from daft.functions import try_decode ( daft.datasets.common_crawl(CC-MAIN-2025-33, contenttext, num_files1) .with_column(text_content, try_decode(daft.col(warc_content), charsetutf-8)) .where(daft.col(text_content).not_null()) .select(WARC-Target-URI, text_content) .limit(3) .show() )文档给出的输出节选显示首行是warcinfo记录WARC-Target-URI为 None内容是Software-Info: ia-web-commons…工具信息后续行则是真实网页文本例如中文的基金资讯页面与俄文促销页面——这也提醒你在抽取语料时应先按WARC-Type conversion/response过滤再叠加语言检测与质量过滤。参数速查表参数取值默认说明crawl字符串如CC-MAIN-2025-33必填爬取批次 ID决定清单路径crawl-data/{crawl}/…segment字符串如1754151279521.11None只读指定 segment每个 crawl 分 100 个 segmentcontentraw/warc、text/wet、metadata/watraw选择 WARC 原始文件、抽取文本或元数据num_files正整数None限制处理的文件数0抛ValueErrorio_configdaft.io.IOConfigNone同时作用于清单下载与read_warc数据读取in_awsboolFalse已弃用v0.9.0 移除等价于sources3sources3/hf/http/NoneNoneNone时优先 HF不可用则自动降级 HTTPS3 必须显式指定以避免 egress 费用补充底层 read_warc 本身还接受file_path_column把源文件路径附加为列、_multithreaded_ioRay runner 下调低并发与checkpoint配合 Ray runner 的断点续跑参数直接调用daft.read_warc时可用common_crawl()封装则只透传io_config。下一步如果想看一个可运行的端到端示例——加载 Common Crawl 并用 Qwen3 做文本向量化可参考 Getting Started with Common Crawl in Daft 教程。使用 Common Crawl 这类数据集做预训练时内容去重对模型表现至关重要可参考 MinHash 去重示例 了解如何在 Daft 中实现。完整的参数文档见 Common Crawl Dataset API Reference。小结与适用边界Daft 对 Common Crawl 的接入设计围绕三个核心权衡展开成本S3 egress vs HF 免费 vs HTTP 慢、数据形态raw / text / metadata 三选一决定 I/O 体量与调试粒度segmentnum_files组合支持“1 个文件”级别的快速迭代。需要注意的边界是HF 源目前仅覆盖 2026 年及之后的 crawlin_aws将在 v0.9.0 移除API 整体处于 beta 状态签名可能随数据集演进而调整。对于历史 crawl2025 及之前在 AWS 外部的访问HTTP 源仍是兜底选项而 WARC 单行较大的特性意味着生产负载建议始终配合文件数限制与合理的分区策略运行。【免费下载链接】DaftHigh-performance data engine for AI and multimodal workloads. Process images, audio, video, and structured data at any scale项目地址: https://gitcode.com/GitHub_Trending/da/Daft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考