CAMEL Loaders 模块完全指南从文档解析、网页抓取到 RAG 数据接入【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camelCAMEL 的 Loaders数据加载器模块是连接 Agent 与外部世界的数据入口它围绕 camel/loaders 包提供了一整套结构化的数据摄取能力Base IO 负责把 PDF、DOCX、HTML 等本地文件统一表示为File对象Unstructured IO 提供从解析、清洗、抽取、分块到平台化的完整 ETL 流水线Firecrawl Reader 将整站网页转为 LLM-ready 的 MarkdownJina URL Reader 则通过 Jina AI 的服务输出更干净的 LLM 友好文本。读完本文你将掌握如何使用camel.loaders完成多格式文档解析、网页内容摄取与清洗、结构化抽取以及如何把这些能力接入 RAG 或 Agent 工作流。本文基于 docs/camel.loaders.rstSphinx autodoc 索引与其指向的四个核心模块源码展开并结合 docs/key_modules/loaders.md 中的实战示例与 test/loaders 下的测试用例进行验证。模块总览camel.loaders 的组成与导出camel.loaders包位于 camel/loaders其init.py 统一导出了全部公开类与函数导出符号用途File/create_file/create_file_from_raw_bytesBase IO多格式文件的统一表示与创建UnstructuredIO非结构化数据的解析、清洗、抽取、分块、stagingJinaURLReader基于 Jina AI Reader 服务的 URL 内容读取Firecrawl基于 Firecrawl API 的整站抓取与爬取ApifyApify 云爬虫编排Actor 运行、数据集读取ChunkrReader/ChunkrReaderConfigChunkr API 文档分块与 OCRMinerUPDF/文档解析抽取MinerU 引擎Crawl4AI基于 Crawl4AI 的异步网页抓取MarkItDownLoader将 HTML、DOCX、PDF 等转为 MarkdownScrapeGraphAI基于大模型的网页结构化抽取MistralReaderMistral OCR 的文本抽取本地/远程 PDF 与图片docs/camel.loaders.rst是这套 API 文档的 autodoc 索引其Submodules一节通过automodule指令将四个核心模块的 docstring 自动生成为 API 参考camel.loaders.base_io文件输入输出抽象camel.loaders.firecrawl_readerFirecrawl 网页抓取封装camel.loaders.jina_url_readerJina URL 读取封装camel.loaders.unstructured_io非结构化数据 ETL 封装。此外__init__.py中定义了一个模块级__getattr__访问已被移除的PandasReader时会抛出带明确指引的ImportError提示改用 camel/toolkits/excel_toolkit.py 处理结构化数据——这是迁移到新架构时容易踩到的坑值得留意。从源码结构看所有 loader 还遵循一个统一的抽象基类 camel/loaders/base_loader.pyBaseLoader它定义了load()批量加载、_load_single()单源加载与supported_formats属性三个抽象契约load()支持传入单个路径或路径列表并统一返回{contents: [...]}结构。Base IO把多格式文件统一为 File 对象camel.loaders.base_io是 Loaders 的地基模块核心目标是无论输入是 PDF、DOCX、TXT、JSON 还是 HTML都以统一的File对象呈现方便后续 Agent 直接消费。File 抽象基类Filecamel/loaders/base_io.py是抽象基类核心字段包括字段说明name文件名file_id文件的唯一标识符由内容 MD5 计算metadata附加元数据默认{}docs文档列表每项为{page_content: ..., ...}结构的字典raw_bytes文件原始字节内容File提供from_bytes()抽象类方法、from_raw_bytes()以及copy()深拷贝方法其__repr__与__str__都便于调试时查看文件身份。工厂函数与子类解析逻辑模块提供两个工厂入口create_file(file: BytesIO, filename)按扩展名路由到对应子类create_file_from_raw_bytes(raw_bytes, filename)先把bytes包成BytesIO再调用create_file。create_file内部维护了扩展名到类名的映射表ext_to_cls仅支持docx、pdf、txt、json、html五种扩展名不支持的扩展名会抛出NotImplementedError测试 test_base_io.py 中的test_create_file_not_implemented即覆盖该路径。各子类的解析逻辑均依赖第三方库通过dependencies_required装饰器在缺失依赖时给出清晰提示DocxFile依赖docx2txt用docx2txt.process()提取文本PdfFile依赖fitz即 PyMuPDF逐页调用page.get_text(sortTrue)每个页面生成一个含page_content与page页码的 docTxtFile按 UTF-8 解码JsonFilejson.load后序列化到page_contentHtmlFile依赖bs4用 BeautifulSoup 的html.parser抽取纯文本。所有子类都会调用strip_consecutive_newlines()base_io.py把连续换行压缩为单个换行并以 MD5 内容哈希作为file_id。实战读取 PDF 并访问内容来自 docs/key_modules/loaders.md 的官方示例展示了完整的用法from io import BytesIO from camel.loaders import create_file_from_raw_bytes # 从磁盘读取 PDF 的原始字节 with open(test.pdf, rb) as file: file_content file.read() # 按扩展名自动路由到 PdfFile file_obj create_file_from_raw_bytes(file_content, test.pdf) # 通过 docs 列表访问提取出的内容 print(file_obj.docs[0][page_content])docs列表的结构是后续所有处理流程的统一入口单页文档是包含一个 dict 的列表多页 PDF 则每个页面一项并带页码字段。Unstructured IO非结构化数据的完整 ETL 流水线camel.loaders.unstructured_io是整个 Loaders 中功能最丰富的模块它把 Unstructured 库的能力封装为五个静态方法覆盖解析 → 清洗 → 抽取 → 分块 → staging五个阶段非常适合 RAG 管线和预处理流程。1. 解析parse_file_or_url 与 parse_bytesparse_file_or_url(input_path, **kwargs)unstructured_io.py统一处理文件路径与 URL内部用urlparse判断输入是否为 URL是则调用unstructured.partition.html.partition_html否则调用unstructured.partition.auto.partition文件不存在时抛出FileNotFoundError解析失败时返回空列表并发出警告支持的格式包括csv、doc、docx、epub、image、md、msg、odt、org、pdf、ppt、pptx、rtf、rst、tsv、xlsx。parse_bytes(file: IO[bytes], **kwargs)unstructured_io.py则直接接收字节流同样通过partition处理失败时返回空列表。官方示例解析一个 CNN 新闻网页from camel.loaders import UnstructuredIO uio UnstructuredIO() example_url ( https://www.cnn.com/2023/01/30/sport/empire-state-building-green- philadelphia-eagles-spt-intl/index.html ) elements uio.parse_file_or_url(example_url) print((\n\n.join([str(el) for el in elements])))2. 清洗clean_text_dataclean_text_data(text, clean_optionsNone)unstructured_io.py以清洗砖块cleaning bricks的方式组合 13 种清洗函数clean_extra_whitespace、clean_bullets、clean_ordered_bullets、clean_postfix、clean_prefix、clean_dashes、clean_trailing_punctuation、clean_non_ascii_chars、group_broken_paragraphs、remove_punctuation、replace_unicode_quotes、bytes_string_to_string、translate_text。不传clean_options时使用默认组合replace_unicode_quotes→clean_non_ascii_chars→group_broken_paragraphs→clean_extra_whitespace传入不存在的函数名会抛出ValueError。官方示例example_dirty_text \u201cSome dirty text\u201d with extra spaces and \u2013 dashes. options [ (replace_unicode_quotes, {}), (clean_dashes, {}), (clean_non_ascii_chars, {}), (clean_extra_whitespace, {}), ] cleaned_text uio.clean_text_data( textexample_dirty_text, clean_optionsoptions, ) print(cleaned_text) # 输出Some dirty text with extra spaces and dashes.3. 结构化抽取extract_data_from_textextract_data_from_text(text, extract_type, **kwargs)unstructured_io.py从文本中抽取特定类型的数据extract_type支持extract_datetimetz、extract_email_address、extract_ip_address、extract_ip_address_name、extract_mapi_id、extract_ordered_bullets、extract_text_after、extract_text_before、extract_us_phone_number。官方示例抽取邮箱地址example_email_text Contact me at exampleemail.com. extracted_text uio.extract_data_from_text( textexample_email_text, extract_typeextract_email_address ) print(extracted_text) # 输出[exampleemail.com]4. 分块chunk_elementschunk_elements(elements, chunk_type, **kwargs)unstructured_io.py当前支持chunk_by_title一种分块策略底层调用unstructured.chunking.title.chunk_by_title按标题切分并保持语义完整是 RAG 切片的直接入口chunks uio.chunk_elements(elementselements, chunk_typechunk_by_title) for chunk in chunks: print(chunk) print(\n - * 80)5. Stagingstage_elementsstage_elements(elements, stage_type, **kwargs)unstructured_io.py把解析出的 Element 转换为特定平台或格式convert_to_csv、convert_to_dataframe、convert_to_dict、dict_to_elements、stage_csv_for_prodigy、stage_for_prodigy、stage_for_baseplate、stage_for_datasaur、stage_for_label_box、stage_for_label_studio、stage_for_weaviate。官方示例转为 Baseplate 标注平台格式staged_element uio.stage_elements(elementselements, stage_typestage_for_baseplate) print(staged_element) # 输出形如{rows: [{data: {type: UncategorizedText, element_id: e78902d05b0cb1e4c38fc7a79db450d5, text: CNN\n \xa0—}, metadata: {...}}, ...]}辅助方法create_element_from_textcreate_element_from_text(text, ...)unstructured_io.py用于从纯文本手工构造 Unstructured 的TextElement支持传入element_id、embeddings、filename、file_directory、last_modified、filetype、parent_id等元数据字段为后续处理链提供统一的 Element 结构。Firecrawl Reader整站转 LLM-ready Markdowncamel.loaders.firecrawl_reader.Firecrawlfirecrawl_reader.py封装 Firecrawl 官方 SDK把整个网站或单个页面转为适合 LLM 消费的 Markdown。其_to_dict()工具函数会把 SDK v2 返回的 pydantic 模型如Document、CrawlJob统一model_dump()成普通 dict保证返回数据始终可按下标访问。初始化与凭据构造函数Firecrawl(api_keyNone, api_urlNone)api_key优先取显式传入值否则读取环境变量FIRECRAWL_API_KEYapi_url优先取显式传入值否则读取环境变量FIRECRAWL_API_URL只有显式提供了api_url时才把它转发给 SDKv2 客户端默认使用生产端点。初始化依赖firecrawl包缺失时会通过dependencies_required抛出依赖提示见 test_loaders_decorators.py 的test_firecrawl_missing_dependency。五大能力方法功能关键参数crawl(url, paramsNone, **kwargs)爬取 URL 及所有可达子页面params可传limit、include_paths、scrape_options**kwargs可传poll_interval、timeout等 SDK 参数check_crawl_job(job_id)查询爬取任务状态返回含status的响应scrape(url, paramsNone)抓取单个 URLparams可传formats、only_main_content等structured_scrape(url, response_format)用 LLM 从 URL 抽取结构化数据response_format为 pydanticBaseModel自动生成 JSON Schemamap_site(url, paramsNone)获取站点内所有可访问 URLparams可传search、limitsearch(query, paramsNone)搜索网页并可附带抓取结果页params可传limit、sources、location、scrape_options所有方法在失败时都会包装为带原因的RuntimeError。实战爬取整站并取回 Markdown来自官方文档的两步式用法from camel.loaders import Firecrawl firecrawl Firecrawl() response firecrawl.crawl(urlhttps://www.camel-ai.org/about) print(response[status]) # 输出 completed 表示抓取完成 # 完成后直接访问 LLM-ready 的 markdown print(response[data][0][markdown])返回的data[0][markdown]就是干净、结构化的页面正文可直接进入提示词或向量化流程。值得强调的是structured_scrape它把 pydantic 模型通过formats[{type: json, schema: response_format.model_json_schema()}]传给 Firecrawl让 LLM 按你定义的字段结构从网页抽取数据测试 test_firecrawl.py 中test_structured_scrape_success验证了该链路。Jina URL Reader更干净的 LLM 友好网页文本camel.loaders.jina_url_reader.JinaURLReaderjina_url_reader.py基于 Jina AI 的 Reader 服务端点https://r.jina.ai/官方注释明确说明其输出比 UnstructuredIO 的 URL Reader 更干净、更 LLM 友好可以配置用于替换流水线中的 URL 读取组件。初始化参数参数默认值说明api_keyNoneJina API Key缺省时读取JINA_API_KEY环境变量未设置会发出警告并降低速率限制return_formatJinaReturnFormat.DEFAULT返回内容的详细程度取自 JinaReturnFormat 枚举json_responseFalse是否以 JSON 格式返回timeout30等待页面渲染的最大秒数**kwargs—额外 HTTP 头字段代理、Cookie 等需与 Reader 服务文档列出的 Header 对齐其中JinaReturnFormat枚举定义在 camel/types/enums.pyDEFAULT值为None、MARKDOWNmarkdown、HTMLhtml、TEXTtext。初始化时会构造请求头AuthorizationBearer key、X-Return-Format、Accept请求 JSON 时置为application/json、X-Timeout并过滤掉值为None的字段。使用示例from camel.loaders import JinaURLReader from camel.types.enums import JinaReturnFormat jina_reader JinaURLReader(return_formatJinaReturnFormat.MARKDOWN) response jina_reader.read_content(https://docs.camel-ai.org/) print(response)read_content(url)内部把 URL 拼接到https://r.jina.ai/之后用requests.get携带上述请求头发起请求失败时抛出ValueError测试 test_jina_url_reader.py 的test_read_content_success/test_read_content_fail分别覆盖成功与失败路径。生态扩展其他 Loaders 一瞥虽然docs/camel.loaders.rst的 Submodules 只列出四个模块但包内还有多个官方文档docs/key_modules/loaders.md同步介绍的生产级 Reader它们与上述核心模块共同构成完整的数据摄取矩阵Apifyapify_reader.py编排 Apify 云爬虫典型流程是run_actor(actor_id, run_input)启动 Actor再用get_dataset_items(dataset_id)拉取结果数据集测试覆盖了 Actor 运行与数据集读写全流程test_apify.py。ChunkrReader / ChunkrReaderConfigchunkr_reader.py异步提交文档分块任务ChunkrReaderConfig支持chunk_processing目标分块长度、ocr_strategy如Auto、high_resolutionFalse走更快的老模型等配置典型用法为await chunkr.submit_task(file_path..., chunkr_configconfig)后用get_task_output(task_id...)轮询取回分块 JSON。MarkItDownLoadermarkitdown.pyconvert_file(demo.html)一行把 HTML、DOCX、PDF 等转为 Markdown。MistralReadermistral_reader.py接入 Mistral OCRextract_text(file_path..., pages[5])支持本地/远程 PDF 与图片返回结构化页面、Markdown 与 usage 信息。MinerU、Crawl4AI、ScrapeGraphAI分别提供 PDF 文档抽取、异步网页抓取与大模型驱动的网页结构化抽取。每个 loader 的用法示例都可在 examples/loaders 下找到对应的独立脚本如firecrawl_example.py、jina_url_reader_example.py、unstructured_io_example.py是快速上手的参考模板。与 RAG / Agent 工作流的衔接把上述 Loaders 串起来即可构成一条典型的 Agent 数据接入管线网页摄取用Firecrawl.crawl()或JinaURLReader.read_content()把网页抓成干净的 Markdown/文本本地文档用create_file_from_raw_bytes()统一解析 PDF/DOCX/HTML或用UnstructuredIO.parse_file_or_url()走全格式 ETL清洗与结构化用clean_text_data()去噪、extract_data_from_text()抽取邮箱/IP/日期等实体、structured_scrape()按 Schema 抽取字段分块入库用chunk_elements(chunk_typechunk_by_title)做语义切片再配合 camel/retrievers 的向量检索组件如 vector_retriever.py、hybrid_retrival.py建立索引标注/下游平台用stage_elements()把数据转换为 Prodigy、Label Studio、Weaviate 等平台所需的格式。此外Loaders 与 Agent 工具层也有现成的桥接例如 file_toolkit.py 等 Toolkit 内部会使用 Base IO 的文件抽象而 loaders 的解析结果天然兼容 camel/memories 与 RAG 流程。依赖与安装提示各 loader 的第三方依赖在代码中均通过dependencies_required装饰器按需声明缺失时会抛出包含安装指引的错误对应测试见 test_loaders_decorators.py覆盖 Crawl4AI、Firecrawl、MarkItDown、ScrapeGraphAI 及 Base IO、Unstructured IO 的缺依赖场景。按需安装的典型依赖包括docx2txtDocxFile、fitzPdfFile、bs4HtmlFileunstructuredUnstructuredIO 全功能firecrawlFirecrawl ReaderrequestsJinaURLReader 运行时导入。建议使用本仓库的依赖管理文件 pyproject.toml / uv.lock 安装基础环境再根据实际使用的 Reader 补齐对应依赖使用 Firecrawl、Jina、Mistral、Chunkr 等云服务时还需分别配置FIRECRAWL_API_KEY、JINA_API_KEY等环境变量缺失时 Firecrawl 会因无 Key 报错Jina 则会降级为低速率并告警。小结camel.loaders是 CAMEL 中面向数据摄取的核心模块Base IO 提供统一的多格式文件抽象Unstructured IO 提供覆盖解析、清洗、抽取、分块、staging 的 ETL 能力Firecrawl 与 JinaURLReader 分别从整站爬取与单页精读两个维度解决网页数据的 LLM 化其余 Reader 则补齐了云爬虫、OCR、分块服务等长尾场景。结合 docs/key_modules/loaders.md 的示例与 examples/loaders 的可运行脚本你可以快速把这些能力接入自己的 RAG 与多 Agent 应用为 Agent 建立稳定、干净、结构化的世界数据入口。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考