CAMEL Loaders 全面指南从结构化文件、非结构化文本到网页与 OCR 的多源数据摄取【免费下载链接】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 提供了连接外部世界的统一数据入口支持结构化文件PDF/DOCX/HTML/JSON 等、非结构化文本、网页内容以及图片 OCR 的读取与预处理。本文以 docs/key_modules/loaders.md 为主线结合 camel/loaders 下的源码实现与 examples/loaders 中的真实示例系统讲解 Base IO、Unstructured IO、Apify、Chunkr、Firecrawl、JinaURL、MarkItDown、Mistral 八大数据读取器的核心概念、API 签名、环境变量要求与端到端用法帮助你为 RAG 流水线、Agent 工具链与数据清洗任务挑选合适的摄取方案。Loaders 是什么CAMEL 的 Loaders 提供了灵活多样的数据摄取与处理方式无论是结构化的文件、非结构化的文本、网页内容还是图片中的 OCR 文本都可以通过统一的接口被读取、解析并送入下游 Agent。它们构成了 Agent 与外部世界交互的能力底座。除基础读写能力外项目还陆续加入了Apify Reader、Chunkr Reader、Firecrawl Reader、JinaURL Reader、Mistral Reader等数据读取器用于检索外部数据以增强数据集成与分析能力。所有 Loaders 的公共导出定义在 camel/loaders/init.py目前对外暴露的类包括File、create_file、create_file_from_raw_bytes、UnstructuredIO、JinaURLReader、Firecrawl、Apify、ChunkrReader、ChunkrReaderConfig、MinerU、Crawl4AI、MarkItDownLoader、ScrapeGraphAI、MistralReader。八大数据读取器类型总览读取器定位典型场景Base IO核心文件输入/输出处理 PDF、DOCX、HTML 等格式将文件表示为统一的File对象读取磁盘上的结构化文档Unstructured IO面向非结构化数据的 ETL解析、清洗、抽取、分块、暂存RAG 流水线与数据预处理Apify Reader集成 Apify 平台自动化网页工作流与爬取大规模网页爬取、Actor 管理、数据集操作Chunkr Reader连接 Chunkr API进行文档分块、切分与 OCR从简单文档到扫描版 PDF 的任意文档Firecrawl Reader通过 Firecrawl API 将整个网站转换为 LLM 友好的 Markdown快速摄取网页内容为干净文本JinaURL Reader使用 Jina AI 的 URL 阅读服务干净地提取网页内容从任意 URL 提取 LLM 友好的内容MarkItDown Reader轻量工具将 HTML、DOCX、PDF 等文件转换为 Markdown为 LLM 摄取或分析准备文档Mistral Reader集成 Mistral AI 的 OCR 服务从图片和 PDF 中提取文本本地与远程文件的 OCR 识别Base IO结构化文件的统一读取Base IO 模块的核心设计是按扩展名分派解析器返回统一的File对象。从源码 camel/loaders/base_io.py 可以看到create_file内部维护了一张扩展名到文件类的映射表ext_to_cls { docx: DocxFile, pdf: PdfFile, txt: TxtFile, json: JsonFile, html: HtmlFile, }当前版本原生支持docx、pdf、txt、json、html五种格式其他扩展名会抛出NotImplementedError。每种File子类都实现了from_bytes类方法并利用不同的底层依赖完成解析DocxFile依赖docx2txt提取文本PdfFile依赖fitzPyMuPDF按页提取page_content并附带页码pageTxtFile直接按 UTF-8 解码JsonFilejson.load解析后以ensure_asciiFalse序列化HtmlFile依赖bs4BeautifulSoup抽取纯文本。所有文件类都会用 MD5 哈希生成file_id唯一标识并将原始字节保存在raw_bytes字段中便于后续追溯。从磁盘读取 PDF 的完整示例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() # 根据文件扩展名创建对应的 File 对象 file_obj create_file_from_raw_bytes(file_content, test.pdf) # 拿到 File 对象后即可访问其内容 print(file_obj.docs[0][page_content])create_file_from_raw_bytes接收bytes与文件名内部会先包装成BytesIO再交给create_file分派。File对象的docs字段是一个列表PDF 每个页面一个元素含page页码其余格式通常只有一个元素。若你的数据源已经是BytesIO流也可以直接使用create_file(file, filename)。Unstructured IO非结构化数据的一站式 ETLUnstructuredIO类封装了 Unstructured 库的五大类能力解析parse、清洗clean、抽取extract、分块chunk与暂存stage全部以静态方法形式提供。源码见 camel/loaders/unstructured_io.py依赖unstructured库。1. 从文件或 URL 解析非结构化数据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]))输出节选 The Empire State Building was lit in green and white to celebrate the Philadelphia Eagles’ victory in the NFC Championship game on Sunday – a decision that’s sparked a bit of a backlash in the Big Apple. The Eagles advanced to the Super Bowl for the first time since 2018 after defeating the San Francisco 49ers 31-7...parse_file_or_url会先用urlparse判断输入是 URL 还是本地路径URL 走partition_html(url...)本地文件走partition(file...)Unstructured 的自动分区支持 csv、doc、docx、epub、image、md、msg、odt、org、pdf、ppt、pptx、rtf、rst、tsv、xlsx 等格式。本地文件不存在时会抛出FileNotFoundError。此外还有parse_bytes(file_io, **kwargs)可直接解析字节流。2. 清洗非结构化文本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.clean_text_data内部注册了 13 种清洗砖块cleaning bricksclean_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。选项列表中的键必须与砖块名严格一致否则抛出ValueError不传clean_options时会启用默认清洗组合replace_unicode_quotes→clean_non_ascii_chars→group_broken_paragraphs→clean_extra_whitespace。3. 从文本中抽取结构化信息如邮箱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]extract_data_from_text支持 9 种抽取类型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底层映射到unstructured.cleaners.extract的对应函数不支持的extract_type会抛出ValueError。4. 按标题分块内容chunks uio.chunk_elements(elementselements, chunk_typechunk_by_title) for chunk in chunks: print(chunk) print(\n - * 80)输出节选 The Empire State Building was lit in green and white... -------------------------------------------------------------------------------- Fly Eagles Fly! Were going Green and White... -------------------------------------------------------------------------------- January 29, 2023chunk_elements目前注册了chunk_by_title一种分块策略调用unstructured.chunking.title.chunk_by_title**kwargs可透传 Unstructured 的分块参数如max_characters、new_after_n_chars等。5. 将元素暂存到其他平台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: {filetype: text/html, languages: [eng], page_number: 1, url: https://www.cnn.com/..., emphasized_text_contents: [CNN], emphasized_text_tags: [span]}}, ...stage_elements共支持 11 种暂存类型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可对接 Prodigy、Label Studio、Weaviate 等标注平台与向量数据库。完整示例见 examples/loaders/unstructured_io_example.py。Apify Reader自动化网页工作流与爬取Apify类源码 camel/loaders/apify_reader.py封装了 Apify 平台的客户端初始化时优先使用显式传入的api_key参数否则读取环境变量APIFY_API_KEY两者都缺失时会触发api_keys_required报错。核心流程是初始化客户端 → 配置 Actor 与其运行参数 → 运行 Actor → 从返回结果的defaultDatasetId读取数据集。from camel.loaders import Apify apify Apify() run_input { startUrls: [{url: https://www.camel-ai.org/}], maxCrawlDepth: 0, maxCrawlPages: 1, } actor_result apify.run_actor( actor_idapify/website-content-crawler, run_inputrun_input ) dataset_result apify.get_dataset_items( dataset_idactor_result[defaultDatasetId] ) print(dataset_result)输出节选[{url: https://www.camel-ai.org/, crawl: {loadedUrl: https://www.camel-ai.org/, ...}, metadata: {canonicalUrl: https://www.camel-ai.org/, ...}, ... }]run_actor的完整参数还包括content_type输入内容类型、buildActor 构建版本标签或编号、max_items最大结果数按结果计费的 Actor 不会超出该上限收费、memory_mbytes内存上限 MB、timeout_secs超时秒数、webhooks完成/失败回调通知、wait_secs服务端等待完成的最大秒数缺省则无限等待。Actor 运行失败会抛出RuntimeError。数据集管理方面Apify提供get_dataset、update_dataset(dataset_id, name)、get_dataset_items、get_datasets(unnamed, limit, offset, desc)等方法支持列出、更新与拉取数据集条目。参考示例 examples/loaders/apify_example.py。Firecrawl Reader把网站变成 LLM 就绪的 MarkdownFirecrawl类源码 camel/loaders/firecrawl_reader.py基于 Firecrawl v2 SDK构造函数读取环境变量FIRECRAWL_API_KEY与可选的自建端点FIRECRAWL_API_URL。SDK 返回的 pydantic 模型会通过_to_dict归一化为普通字典保持 JSON 风格的可下标访问行为。第一步初始化客户端并启动爬取from camel.loaders import Firecrawl firecrawl Firecrawl() response firecrawl.crawl(urlhttps://www.camel-ai.org/about) print(response[status]) # 完成后应打印 completedcompletedcrawl支持params如limit、include_paths、scrape_options与**kwargs如poll_interval、timeout。当状态为completed时表示内容抽取完成可以获取结果。对于只想抓取单个页面的场景可以使用scrape(url, params)。第二步取回抽取后的 Markdown 内容print(response[data][0][markdown])输出节选Camel-AI Team We are finding the scaling law of agent CAMEL is an open-source library designed for the study of autonomous and communicative agents...除crawl/scrape外Firecrawl还提供check_crawl_job(job_id)查询异步爬取任务状态structured_scrape(url, response_format)传入 pydanticBaseModel由 LLM 按照 schema 从 URL 抽取结构化数据返回data[json]map_site(url, params)返回站点所有可访问 URL 的列表search(query, params)网页搜索并可选择抓取结果页。完整示例见 examples/loaders/firecrawl_example.py。Chunkr Reader带 OCR 的文档分块处理ChunkrReader与ChunkrReaderConfig源码 camel/loaders/chunkr_reader.py面向分块 OCR 格式控制的文档处理任务。初始化时读取环境变量CHUNKR_API_KEYAPI 地址默认为https://api.chunkr.ai/api/v1/task。ChunkrReaderConfig的三个核心参数及源码默认值参数默认值说明chunk_processing512目标分块长度target chunk lengthhigh_resolutionTrue是否使用高分辨率 OCRFalse对应旧版 Fast 模型、处理更快ocr_strategyAutoOCR 策略Auto或All其他值回退为All其余参数通过**kwargs透传给 Chunkr 的Configuration如expires_in、pipeline、segment_processing、segmentation_strategy等。配置转换发生在_to_chunkr_configuration中chunk_processing被包装为ChunkProcessing(target_length...)。异步提交任务并拉取结果import asyncio from camel.loaders import ChunkrReader, ChunkrReaderConfig async def main(): chunkr ChunkrReader() config ChunkrReaderConfig( chunk_processing512, # 示例目标分块长度 ocr_strategyAuto, # 示例OCR 策略 high_resolutionFalse # False 走更快的处理旧 Fast 模型 ) # 替换为你的真实文件路径 file_path /path/to/your/document.pdf try: task_id await chunkr.submit_task( file_pathfile_path, chunkr_configconfig, ) print(fTask ID: {task_id}) # 轮询并获取输出 if task_id: task_output_json_str await chunkr.get_task_output(task_idtask_id) if task_output_json_str: print(Task Output:) print(task_output_json_str) else: print(fFailed to get output for task {task_id}, or task did not succeed/was cancelled.) except ValueError as e: print(fAn error occurred during task submission or retrieval: {e}) except FileNotFoundError: print(fError: File not found at {file_path}. Please check the path.) except Exception as e: print(fAn unexpected error occurred: {e}) if __name__ __main__: print(To run this example, replace /path/to/your/document.pdf with a real file path, ensure CHUNKR_API_KEY is set, and uncomment asyncio.run(main()).) # asyncio.run(main()) # 取消注释以运行示例submit_task内部调用self._chunkr.create_task(filefile_path, configchunkr_config)提交文件并返回task_idget_task_output会poll()轮询任务仅在Status.SUCCEEDED时返回美化后的 JSON 字符串失败或取消时返回None。成功的任务返回的分块结构包含segments数组每个 segment 带有segment_id、bbox边界框、page_number、page_width/height、content、segment_type如Title、Text、ocr、image、html、markdown等字段可直接用于 RAG 建库。参考示例 examples/loaders/chunkr_example.py。JinaURL Reader任意 URL 的 LLM 友好内容提取JinaURLReader源码 camel/loaders/jina_url_reader.py通过 Jina AI 的https://r.jina.ai/端点读取 URL 内容。相比UnstructuredIO的 URL 解析其输出更干净、更面向 LLM且可以配置为流水线中 URL Reader 的替代方案。关键配置项api_keyJina API Key缺省读取环境变量JINA_API_KEY未设置时仅发出警告限流更低不会报错return_format返回格式枚举JinaReturnFormat定义在 camel/types/enums.pyDEFAULTNone、MARKDOWN、HTML、TEXTjson_response是否返回 JSON 格式timeout等待页面渲染的最大秒数默认 30**kwargs额外的 HTTP 头字段如proxies、cookies与 Jina Reader 文档中列出的 Header 字段对齐。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 拼接为https://r.jina.ai/url后发起 GET 请求请求失败时抛出ValueError。示例见 examples/loaders/jina_url_reader_example.py。MarkItDown Reader一行代码把文件转成 MarkdownMarkItDownLoader源码 camel/loaders/markitdown.py封装微软开源的markitdown转换器支持非常广泛的输入格式SUPPORTED_FORMATS类变量PDF、Word.doc/.docx、Excel.xls/.xlsx、PowerPoint.ppt/.pptx、EPUB、HTML/HTM、图片含 EXIF 元数据与 OCR、音频含语音转写、CSV/JSON/XML、ZIP 压缩包迭代内部内容、YouTube URL提取字幕以及 .md 文件。构造函数可传入可选的llm_client与llm_model以启用基于 LLM 的增强转换。from camel.loaders import MarkItDownLoader loader MarkItDownLoader() response loader.convert_file(demo.html) print(response)输出节选 Welcome to CAMELs documentation! — CAMEL 0.2.61 documentation [Skip to main content](https://docs.camel-ai.org/#main-content) ...convert_file会先校验文件存在性与扩展名合法性不支持的格式抛出ValueError随后调用self.converter.convert(file_path)并返回.text_content。批量场景可使用convert_files(file_paths, parallelFalse, skip_failedFalse)parallelTrue时通过ThreadPoolExecutor并发转换并用 tqdm 显示进度skip_failedTrue时失败文件被跳过并记警告日志否则错误信息会以Error: ...字符串写入结果字典。示例见 examples/loaders/markitdown_example.py。Mistral ReaderPDF 与图片的 OCR 文本提取MistralReader源码 camel/loaders/mistral_reader.py集成 Mistral AI 的 OCR 服务支持 PDF 与图片的本地文件、远程 URL 两种输入。初始化读取环境变量MISTRAL_API_KEY默认模型为mistral-ocr-latest可通过model参数覆盖。from camel.loaders import MistralReader mistral_reader MistralReader() # 从 PDF URL 提取文本只处理第 5 页页码从 0 开始 url_ocr_response mistral_reader.extract_text( file_pathhttps://arxiv.org/pdf/2201.04234, pages[5] ) print(url_ocr_response)也支持图片与本地文件# 从图片 URL 提取文本 image_ocr_response mistral_reader.extract_text( file_pathhttps://raw.githubusercontent.com/mistralai/cookbook/refs/heads/main/mistral/ocr/receipt.png, is_imageTrue, ) print(image_ocr_response)# 从本地 PDF 文件提取文本 local_ocr_response mistral_reader.extract_text(path/to/your/document.pdf) print(local_ocr_response)extract_text的参数is_image控制使用image_url还是document_url类型pages指定要处理的页码列表从 0 开始仅对文档生效include_image_base64决定响应中是否包含图片的 base64 数据。本地文件会先被 base64 编码后以data:URI 形式发送远程 URL 则直接透传。响应是OCRResponse对象包含按页组织的结构化数据、Markdown 内容与用量信息 pages[OCRPageObject(index5, markdownimg-0.jpeg\n\nFigure 2: Scatter plot of predicted accuracy versus (true) OOD accuracy..., images[OCRImageObject(idimg-0.jpeg, ...)], dimensionsOCRPageDimensions(...))] modelmistral-ocr-2505-completion usage_info...示例见 examples/loaders/mistral_example.py。如何选择适合你的 Loader根据任务类型可以快速定位合适的读取器本地结构化文档PDF/DOCX/TXT/JSON/HTML使用 Base IO 的create_file_from_raw_bytes/create_file得到统一的File对象与docs列表RAG 预处理全流程解析→清洗→抽取→分块→暂存使用UnstructuredIO一条调用链完成从 URL 到可入库 chunk 的转换整站抓取与网页级爬取需要云平台 Actor 编排选Apify追求站点→干净 Markdown选Firecrawl或单页用其scrape扫描版 PDF / 复杂版式文档的分块 OCR选ChunkrReader自带 OCR 与分块任务单 URL 快速读取、要求输出格式可控Markdown/HTML/Text选JinaURLReader多格式批量转 Markdown含 Office、音视频、ZIP选MarkItDownLoader支持并发批量转换PDF/图片 OCR 文本抽取需要结构化页级输出选MistralReader。除本文覆盖的八类读取器外camel/loaders 还提供Crawl4AI、MinerU、ScrapeGraphAI等读取器可结合 examples/loaders 下的对应示例进一步探索。接入这些 Loader 时只需牢记一点多数云端服务通过环境变量注入密钥APIFY_API_KEY、FIRECRAWL_API_KEY、CHUNKR_API_KEY、JINA_API_KEY、MISTRAL_API_KEY配置好密钥即可在 Agent 与 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/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考