CAMEL 中的 JinaURLReader：使用 Jina AI 服务提取 LLM 友好的网页内容

CAMEL 中的 JinaURLReader使用 Jina AI 服务提取 LLM 友好的网页内容【免费下载链接】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导读JinaURLReader是 CAMEL 框架 camel/loaders 模块提供的网页内容读取器它基于 Jina AI 的 URL 读取服务https://r.jina.ai/将任意网页转换为干净、结构化的 Markdown/文本内容输出比 UnstructuredIO 的 URL Reader 更干净、更适合作为 LLM 输入。读完本文你将掌握JinaURLReader的完整参数语义、环境变量与请求头的对应关系、四种返回格式的区别以及如何在 CAMEL 的 Agent 数据摄取管线中用一行代码替换原有的 URL 解析方案。JinaURLReader 是什么在 CAMEL 的 Loaders 体系中JinaURLReader属于Web 内容摄取类读取器与 Apify Reader、Firecrawl Reader、Chunkr Reader、Mistral Reader 并列专门负责从 URL 中提取外部数据以增强数据集成与分析。其类注释见 jina_url_reader.py明确说明了它的定位URL Reader provided by Jina AI. The output is cleaner and more LLM-friendly than the URL Reader of UnstructuredIO. Can be configured to replace the UnstructuredIO URL Reader in the pipeline.也就是说它输出的内容比 UnstructuredIO 的 URL Readerparse_file_or_url更干净、更利于大模型理解并且可以配置为在数据摄取管线中直接替代 UnstructuredIO 的 URL Reader。如果你的管线此前依赖 unstructured_io.py 中的parse_file_or_url来抓取网页那么JinaURLReader是一个更轻量、输出质量更高的替代品。安装与导入JinaURLReader由camel.loaders包统一导出无需额外安装依赖requests为运行时导入。从 camel/loaders/__init__.py 可以看到导出声明from .jina_url_reader import JinaURLReader使用方式from camel.loaders import JinaURLReader from camel.types.enums import JinaReturnFormat reader JinaURLReader(return_formatJinaReturnFormat.MARKDOWN) content reader.read_content(https://docs.camel-ai.org/) print(content)构造参数详解JinaURLReader的构造签名见 jina_url_reader.py如下def __init__( self, api_key: Optional[str] None, return_format: JinaReturnFormat JinaReturnFormat.DEFAULT, json_response: bool False, timeout: int 30, **kwargs: Any, ) - None:参数类型默认值说明api_keyOptional[str]NoneJina AI 的 API Key。不提供时读取环境变量JINA_API_KEY若两者皆无读取器会以较低速率限制运行并发出警告return_formatJinaReturnFormatJinaReturnFormat.DEFAULT返回内容的详细程度专为 LLM 优化。目前不支持截图json_responseboolFalse是否以 JSON 格式返回响应timeoutint30等待页面渲染的最大秒数**kwargsAny—额外关键字参数如代理proxies、cookies 等需与 Jina Reader 参考文档中列出的 HTTP Header 字段及取值对齐关于 API Key 的降级策略从源码 jina_url_reader.py 可以看到api_key参数的优先级高于环境变量api_key api_key or os.getenv(JINA_API_KEY) if not api_key: warn( JINA_API_KEY not set. This will result in a low rate limit of Jina URL Reader. Get API key here: https://jina.ai/reader. )若显式传入api_key则直接使用否则回退到环境变量JINA_API_KEY两者皆缺省时程序不会报错而是发出UserWarning提示速率限制较低。因此生产环境强烈建议通过export JINA_API_KEY...或显式传参配置密钥。请求头的构造逻辑底层原理JinaURLReader的核心机制非常透明构造时把参数翻译为 HTTP Header请求时拼接到 Jina 的读取端点。从 jina_url_reader.py 可以看到# if the following field not provided, it will be None api_field fBearer {api_key} if api_key else None json_field application/json if json_response else None raw_headers { Authorization: api_field, X-Return-Format: return_format.value, Accept: json_field, X-Timeout: str(timeout), **kwargs, } # eliminate None values self._headers {k: v for k, v in raw_headers.items() if v}参数与请求头的映射关系如下构造参数对应的 HTTP Header值示例api_keyAuthorizationBearer jina_xxxx未提供时为None并被剔除return_formatX-Return-Formatmarkdown/html/text/Nonejson_responseAcceptapplication/jsonFalse时剔除timeoutX-Timeout30**kwargs直接并入请求头如proxies、cookie等 Jina Reader 文档支持的字段值得注意的实现细节是值为None的请求头会被显式剔除{k: v for k, v in raw_headers.items() if v}这避免了把Authorization: None之类的空头发给服务端保证不带 API Key 或不开 JSON 输出时的请求依然合法。返回格式ReturnFormat详解return_format的类型为JinaReturnFormat定义在 camel/types/enums.pyclass JinaReturnFormat(Enum): DEFAULT None MARKDOWN markdown HTML html TEXT text枚举值底层值适用场景JinaReturnFormat.DEFAULTNone默认格式针对 LLM 输入优化不设置X-Return-Format头JinaReturnFormat.MARKDOWNmarkdown需要保留标题、表格、列表结构时首选便于 RAG 分块JinaReturnFormat.HTMLhtml需要原始页面结构、进一步自定义解析时JinaReturnFormat.TEXTtext只需要纯文本、追求最小 token 占用时由于枚举成员DEFAULT的值为None当选择默认格式时X-Return-Format头会被自动剔除由 Jina 服务端返回其默认LLM 友好格式。核心方法 read_contentJinaURLReader的对外接口只有一个方法见 jina_url_reader.pydef read_content(self, url: str) - str: rReads the content of a URL and returns it as a string with given form. import requests full_url f{JINA_ENDPOINT}{url} try: resp requests.get(full_url, headersself._headers) resp.raise_for_status() except Exception as e: raise ValueError(fFailed to read content from {url}: {e}) from e return resp.text端点拼接规则模块级常量JINA_ENDPOINT https://r.jina.ai/见 jina_url_reader.py定义了 Jina Reader 的服务端点。read_content将目标 URL 直接拼接在端点之后即最终请求地址为https://r.jina.ai/你的URL例如读取维基百科页面时实际请求https://r.jina.ai/https://en.wikipedia.org/wiki/Hollow_Knight。返回值形态方法返回resp.text字符串。以测试用例 test/loaders/test_jina_url_reader.py 中 mock 的响应为例典型的 Markdown 输出包含以下结构Title: Hollow Knight URL Source: https://en.wikipedia.org/wiki/Hollow_Knight Published Time: 2017-03-05T15:54:50Z Markdown Content: | Hollow Knight | | --- | | Developer(s) | Team Cherry | ...即页面标题、URL 来源、发布时间、以及经过清洗的 Markdown 正文这正是更干净、更 LLM 友好的具体体现——去除了导航、脚本、广告等噪音。异常处理任何请求异常网络错误、非 2xx 状态码等都会被捕获并统一包装为ValueError(fFailed to read content from {url}: {e})抛出测试用例 test/loaders/test_jina_url_reader.py 模拟了 Jina 服务端返回 422如页面导航超时的场景验证read_content会正确抛出ValueError。因此在调用时建议用try/except ValueError兜底from camel.loaders import JinaURLReader reader JinaURLReader() try: content reader.read_content(https://en.wikipedia.org/wiki/Hollow_Knight) print(content) except ValueError as e: print(f读取失败: {e})实战示例按需切换返回格式仓库提供了完整的交互式示例 examples/loaders/jina_url_reader_example.py演示如何遍历四种返回格式并控制 JSON 输出from camel.loaders import JinaURLReader from camel.types.enums import JinaReturnFormat def read_with_different_format(return_format, json_response): URL https://en.wikipedia.org/wiki/Miss_Meyers jina_url_reader JinaURLReader( return_formatreturn_format, json_responsejson_response ) content jina_url_reader.read_content(URL) print(content) def main(): formats [ JinaReturnFormat.DEFAULT, JinaReturnFormat.TEXT, JinaReturnFormat.HTML, JinaReturnFormat.MARKDOWN, ] print(Choose a return format of read content:) print(1. Default, optimized for LLM inputs) print(2. Pure Text) print(3. HTML) print(4. Markdown) choice input(Enter your choice (1-4): ) if not choice.isnumeric() or int(choice) 1 or int(choice) 4: print(Invalid choice. Exiting.) return return_format formats[int(choice) - 1] json_response input(Do you want the response in JSON format? (y/N): ) json_response json_response.lower() y read_with_different_format(return_format, json_response) if __name__ __main__: main()运行该示例后按提示选择 1–4 即可分别体验LLM 优化默认格式 / 纯文本 / HTML / Markdown输入y则会设置Accept: application/json头让服务端返回 JSON 包装的响应体。在 RAG / Agent 管线中的典型用法JinaURLReader的典型定位是作为 Agent 网页信息摄取的第一步抓取网页 → 得到干净 Markdown → 分块 → 向量化检索。例如将读取结果交给 CAMEL 的检索器或直接作为上下文注入 LLMfrom camel.loaders import JinaURLReader from camel.types.enums import JinaReturnFormat # 构造 Markdown 模式的读取器LLM 友好 reader JinaURLReader( api_keyjina_your_key, # 或设置环境变量 JINA_API_KEY return_formatJinaReturnFormat.MARKDOWN, timeout60, # 页面渲染等待上限 ) content reader.read_content(https://docs.camel-ai.org/) # 后续可将 content 交给 chunker 分块、embedding 后写入向量库 # 或直接拼入 prompt 作为上下文。 print(content[:2000])测试验证与行为契约仓库中 test/loaders/test_jina_url_reader.py 覆盖了该类的两条核心行为契约成功路径test_read_content_successmockrequests.get返回 200 及含Title: Hollow Knight的 Markdown 文本断言read_content返回的内容包含标题。这验证了URL 内容以字符串返回的契约。失败路径test_read_content_failmock 服务端返回 422模拟页面加载超时断言read_content抛出ValueError。这验证了所有异常统一包装为 ValueError的契约。两者都通过from camel.loaders import JinaURLReader导入也间接证明了该类的公开导出路径。小结JinaURLReader为 CAMEL 的数据摄取层提供了一个零样板boilerplate-free的网页转文本方案一行构造、一行读取JinaURLReader(...)read_content(url)即可拿到 LLM 友好的 Markdown参数即请求头api_key/return_format/json_response/timeout直接映射为Authorization/X-Return-Format/Accept/X-Timeout语义透明API Key 三层降级显式参数 → 环境变量JINA_API_KEY→ 无 Key 低限流运行并告警异常统一所有失败场景收敛为ValueError便于上层捕获可替换 UnstructuredIO官方类注释明确其可作为 UnstructuredIO URL Reader 的替代接入既有管线。当你的 Agent 需要频繁抓取网页做检索增强或上下文补充且希望输出直接可喂给 LLM 时JinaURLReader是 camel.loaders 中最轻量的选择之一。更多 Loaders 整体能力可参阅 Loaders 模块文档。【免费下载链接】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），仅供参考