LlamaIndex Oxylabs Reader 集成指南从搜索引擎与电商平台抓取结构化数据【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读本文基于 LlamaIndex 仓库中的 Oxylabs Reader API 参考文档 及配套源码系统讲解llama-index-readers-oxylabs集成包的完整用法。该集成将 Oxylabs 商业爬虫 API 封装为 LlamaIndex 的标准 Reader让开发者能够以统一的load_data()接口将搜索引擎、电商平台、旅行平台等网站的结构化数据直接转换成 LlamaIndexDocument对象用于 RAG、检索增强生成等下游任务。读完本文你将掌握 9 个专用 Reader 的选型、安装配置、同步/异步调用方式并理解其底层的响应校验与 JSON-to-Markdown 转换机制。一、Oxylabs Reader 是什么Oxylabs Reader 是 LlamaIndex 官方生态中负责网页数据摄取的一类 Reader。它通过 Oxylabs 提供的 Web Scraper API将目标网站搜索页、商品页、评论页、视频字幕等的抓取结果转换为 LlamaIndex 可消费的Document列表。从仓库结构看该集成位于llama-index-integrations/readers/llama-index-readers-oxylabs/包版本为 0.2.1见 pyproject.toml依赖oxylabs2.0.0官方 SDK 以及llama-index-core0.12.34.post1。该包的核心价值在于屏蔽了 HTTP 抓取、反爬、响应解析的复杂性。开发者只需要传入用户名/密码和业务参数query、domain、geo_location 等即可获得已经清洗、格式化的文档内容特别适合构建电商比价、市场调研、舆情分析、SEO 监控等数据密集型应用。根据 API 参考文档该模块共导出 10 个类其中 1 个抽象基类、9 个具体 Reader类名用途OxylabsBaseReader抽象基类承载通用逻辑凭证初始化、响应校验、文档构建OxylabsAmazonSearchReader亚马逊搜索结果页数据OxylabsAmazonPricingReader亚马逊商品报价列表offer listingsOxylabsAmazonProductReader亚马逊商品详情页数据OxylabsAmazonSellersReader亚马逊卖家店铺信息OxylabsAmazonBestsellersReader亚马逊 Best Sellers 畅销榜页面OxylabsAmazonReviewsReader亚马逊商品评论OxylabsGoogleSearchReaderGoogle 搜索结果含知识图谱、本地信息等OxylabsGoogleAdsReaderGoogle 搜索结果中的付费广告OxylabsYoutubeTranscriptReaderYouTube 视频字幕文本上述类的实际导出可在init.py 中确认。二、安装与凭证准备2.1 安装方式该包可通过多种包管理器安装以下命令来自 README.md# pip pip install llama-index-readers-oxylabs # poetry poetry add llama-index-readers-oxylabs # uv uv add llama-index-readers-oxylabs2.2 获取 Oxylabs 凭证使用前需要先注册 Oxylabs 账户获得 API 访问所需的用户名username和密码password。这两个凭证将用于构建 SDK 客户端。三、快速上手以 Google 搜索为例参考文档与 README 给出的最小可用示例如下from llama_index.readers.oxylabs import OxylabsGoogleSearchReader reader OxylabsGoogleSearchReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs reader.load_data( {query: Iphone 16, parse: True, geo_location: Berlin, Germany} ) print(docs[0].text)运行后docs[0].text即为结构化文本其中会包含ORGANIC RESULTS ITEMS、SEARCH INFORMATION、RELATED SEARCHES ITEMS等分类片段见 tests/test_readers_oxylabs.py 中的集成测试断言。四、9 个专用 Reader 逐一解析4.1 Amazon 系列6 个 ReaderAmazon 系列 Reader 均继承OxylabsBaseReader内部通过self.oxylabs_api.amazon的不同方法发起抓取并各自设置top_level_header用于生成文档的顶层标题。对应源码位于llama-index-integrations/readers/llama-index-readers-oxylabs/llama_index/readers/oxylabs/目录Reader底层调用方法顶层标题典型 payload 参数OxylabsAmazonSearchReaderscrape_search(**payload)Search Resultsquery、parse、domainOxylabsAmazonPricingReaderscrape_pricing(**payload)Product pricing dataquery商品 ASIN、parseOxylabsAmazonProductReaderscrape_product(**payload)ProductsqueryASIN、parseOxylabsAmazonSellersReaderscrape_sellers(**payload)Sellersquery卖家 ID、parseOxylabsAmazonBestsellersReaderscrape_bestsellers(**payload)Bestsellerssource、domain、query、render、start_page、parseOxylabsAmazonReviewsReaderscrape_reviews(**payload)ReviewsqueryASIN、parse其中各实现文件分别为 amazon_search.py、amazon_pricing.py、amazon_product.py、amazon_sellers.py、amazon_bestsellers.py、amazon_reviews.py。以亚马逊商品搜索为例from llama_index.readers.oxylabs import OxylabsAmazonSearchReader reader OxylabsAmazonSearchReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs reader.load_data( { query: headsets, domain: com, parse: True, } )4.2 Google 系列2 个 ReaderOxylabsGoogleSearchReader与OxylabsGoogleAdsReader都继承自中间层OxylabsGoogleBaseReadergoogle_base.py该中间层对 Google 搜索结果做了细粒度的分类解析。OxylabsGoogleAdsReader用于单独获取付费广告结果底层调用scrape_ads(**payload)。from llama_index.readers.oxylabs import OxylabsGoogleAdsReader reader OxylabsGoogleAdsReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs reader.load_data({query: iPhone 16, parse: True})4.3 YouTube 字幕1 个 ReaderOxylabsYoutubeTranscriptReader通过self.oxylabs_api.youtube_transcript.scrape_transcript(**payload)获取视频字幕顶层标题为YouTube video transcripts。测试用例展示了其典型参数结构from llama_index.readers.oxylabs import OxylabsYoutubeTranscriptReader reader OxylabsYoutubeTranscriptReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs reader.load_data( { query: SLoqvcnwwN4, # YouTube 视频 ID context: [ {key: language_code, value: en}, {key: transcript_origin, value: uploader_provided}, ], } )五、源码级原理数据如何变成 Document5.1 基类的统一处理管线所有 Reader 的核心逻辑集中在OxylabsBaseReaderbase.py构造阶段__init__接收username、password同时创建同步客户端RealtimeClient与异步客户端AsyncClient并附加sdk_type标识格式为oxylabs-llama-index-oxy-sdk-python/包版本 (Python 版本; 架构位数)便于服务端识别调用来源。加载阶段load_data(payload)调用子类实现的get_response(payload)拿到Response经_validate_response校验后调用_get_document_from_response生成Document。异步对应aload_data(payload)使用aget_response(payload)返回类型与同步版一致便于在 asyncio 环境中使用。每个子类只需实现get_response/aget_response两个方法即可接入新的目标站点这也是该设计可扩展性最好的体现。5.2 响应校验逻辑_validate_response基类对 Oxylabs 返回的原始响应做了严格校验读取response.raw[results]若结果不是非空列表则抛出ValueError(No results returned!)对每个结果页若content本身是列表则直接采用若content为字典优先提取其中的results字段列表或字典均可若content既不是列表也不是字典则提示请将parse参数设置为 True。这正是 README 示例中parse: True至关重要的原因——该参数让 API 返回结构化的 JSON 而非原始 HTML。5.3 JSON 转 Markdownjson_to_markdown对于 Amazon 系列与 YouTube 系列转换由工具函数json_to_markdownutils.py完成。它递归地将 JSON 结构转为 Markdown字典的每个 key 生成为对应层级的标题层级上限为 6 级######列表项生成- Item N:列表多行字符串以引用块形式呈现空列表输出- *Empty List*占位。单元测试验证了输出格式例如docs[0].text应符合# {top_level_header}\n- Item 1:\n ## key1\n value1\n\n ## key2\n value2\n的结构见 test_readers_oxylabs.py。5.4 Google 结果分类解析OxylabsGoogleBaseReaderGoogle 系列走的是另一套更精细的解析路径。OxylabsGoogleBaseReader预定义了 5 大结果分类RESULT_CATEGORIESknowledge_graph知识图谱、combined_search_result综合搜索结果、product_information商品信息、local_information本地信息、search_information搜索信息。解析时通过递归收集器_recursive_snippet_collector默认递归深度parsing_recursion_depth5把嵌套 JSON 展平为带缩进与标签的文本片段例如集成测试断言中出现的ORGANIC RESULTS ITEMS、SEARCH INFORMATION、RELATED SEARCHES ITEMS等。值得注意的细节配置include_binary_image_data: bool False默认不保留图片二进制数据相关字段如image_data、data、images数组会被替换为占位符Redacted base64 image string...避免向 LLM 上下文注入大量无意义 base64 内容excluded_result_attributes: list[str] [pos_overall]默认剔除pos_overall这类位置元数据保持文档简洁。六、payload 参数实战参考以下参数组合直接取自仓库的单元/集成测试参数化用例tests/test_readers_oxylabs.py可放心作为实际调用模板Amazon Bestsellers{source: amazon_bestsellers, domain: com, query: 120225786011, render: html, start_page: 1, parse: True}Amazon Pricing / Product / Reviews{query: B087TXHLVQ, parse: True}query 传 ASINAmazon Sellers{query: A2U55XLSPNCN01, parse: True}query 传卖家 IDAmazon Search{query: headsets, parse: True}Google Search / Ads{query: iPhone 16, parse: True}YouTube Transcript{query: video_id, context: [{key: language_code, value: en}, {key: transcript_origin, value: uploader_provided}]}Google SearchREADME 增强版额外支持geo_location如Berlin, Germany等地理参数注意事项这些 Reader 的load_data始终返回恰好一个Document的列表所有结果页被合并进同一文档这是基类load_data的实现行为单元测试通过 Mock 覆盖了全部 8 个具体 Reader 的同步与异步路径test_sync_oxylabs_readers/test_async_oxylabs_readers而 Google 系列另有需要真实凭证环境变量OXYLABS_USERNAME、OXYLABS_PASSWORD的集成测试未设置凭证时会被自动跳过。七、异步调用与常见问题7.1 异步用法所有 Reader 均支持 asyncioimport asyncio from llama_index.readers.oxylabs import OxylabsAmazonProductReader async def main(): reader OxylabsAmazonProductReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs await reader.aload_data({query: B087TXHLVQ, parse: True}) print(docs[0].text) asyncio.run(main())7.2 常见报错与排查现象原因与处理Response Validation Error: No results returned!响应中results为空检查 query 参数或配额Result content format error, try setting parameter parse to True返回了非结构化内容请在 payload 中显式设置parse: True文档中包含Redacted base64 image string...正常行为图片二进制默认被脱敏如需原图数据可设置include_binary_image_dataTrue会增加 token 消耗集成测试被跳过未设置OXYLABS_USERNAME/OXYLABS_PASSWORD环境变量属预期行为八、总结llama-index-readers-oxylabs将商业级爬虫能力与 LlamaIndex 文档体系无缝衔接通过 base.py 的响应校验、utils.py 的 JSON-to-Markdown 转换以及 google_base.py 的分类化解析实现了一次编写、多源复用。无论是构建电商监控、SEO 研究还是视频内容检索管线只需按本文选择对应 Reader、配置凭证与 payload即可将抓取数据直接送入 LlamaIndex 的索引与查询流程。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LlamaIndex Oxylabs Reader 集成指南：从搜索引擎与电商平台抓取结构化数据
LlamaIndex Oxylabs Reader 集成指南从搜索引擎与电商平台抓取结构化数据【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读本文基于 LlamaIndex 仓库中的 Oxylabs Reader API 参考文档 及配套源码系统讲解llama-index-readers-oxylabs集成包的完整用法。该集成将 Oxylabs 商业爬虫 API 封装为 LlamaIndex 的标准 Reader让开发者能够以统一的load_data()接口将搜索引擎、电商平台、旅行平台等网站的结构化数据直接转换成 LlamaIndexDocument对象用于 RAG、检索增强生成等下游任务。读完本文你将掌握 9 个专用 Reader 的选型、安装配置、同步/异步调用方式并理解其底层的响应校验与 JSON-to-Markdown 转换机制。一、Oxylabs Reader 是什么Oxylabs Reader 是 LlamaIndex 官方生态中负责网页数据摄取的一类 Reader。它通过 Oxylabs 提供的 Web Scraper API将目标网站搜索页、商品页、评论页、视频字幕等的抓取结果转换为 LlamaIndex 可消费的Document列表。从仓库结构看该集成位于llama-index-integrations/readers/llama-index-readers-oxylabs/包版本为 0.2.1见 pyproject.toml依赖oxylabs2.0.0官方 SDK 以及llama-index-core0.12.34.post1。该包的核心价值在于屏蔽了 HTTP 抓取、反爬、响应解析的复杂性。开发者只需要传入用户名/密码和业务参数query、domain、geo_location 等即可获得已经清洗、格式化的文档内容特别适合构建电商比价、市场调研、舆情分析、SEO 监控等数据密集型应用。根据 API 参考文档该模块共导出 10 个类其中 1 个抽象基类、9 个具体 Reader类名用途OxylabsBaseReader抽象基类承载通用逻辑凭证初始化、响应校验、文档构建OxylabsAmazonSearchReader亚马逊搜索结果页数据OxylabsAmazonPricingReader亚马逊商品报价列表offer listingsOxylabsAmazonProductReader亚马逊商品详情页数据OxylabsAmazonSellersReader亚马逊卖家店铺信息OxylabsAmazonBestsellersReader亚马逊 Best Sellers 畅销榜页面OxylabsAmazonReviewsReader亚马逊商品评论OxylabsGoogleSearchReaderGoogle 搜索结果含知识图谱、本地信息等OxylabsGoogleAdsReaderGoogle 搜索结果中的付费广告OxylabsYoutubeTranscriptReaderYouTube 视频字幕文本上述类的实际导出可在init.py 中确认。二、安装与凭证准备2.1 安装方式该包可通过多种包管理器安装以下命令来自 README.md# pip pip install llama-index-readers-oxylabs # poetry poetry add llama-index-readers-oxylabs # uv uv add llama-index-readers-oxylabs2.2 获取 Oxylabs 凭证使用前需要先注册 Oxylabs 账户获得 API 访问所需的用户名username和密码password。这两个凭证将用于构建 SDK 客户端。三、快速上手以 Google 搜索为例参考文档与 README 给出的最小可用示例如下from llama_index.readers.oxylabs import OxylabsGoogleSearchReader reader OxylabsGoogleSearchReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs reader.load_data( {query: Iphone 16, parse: True, geo_location: Berlin, Germany} ) print(docs[0].text)运行后docs[0].text即为结构化文本其中会包含ORGANIC RESULTS ITEMS、SEARCH INFORMATION、RELATED SEARCHES ITEMS等分类片段见 tests/test_readers_oxylabs.py 中的集成测试断言。四、9 个专用 Reader 逐一解析4.1 Amazon 系列6 个 ReaderAmazon 系列 Reader 均继承OxylabsBaseReader内部通过self.oxylabs_api.amazon的不同方法发起抓取并各自设置top_level_header用于生成文档的顶层标题。对应源码位于llama-index-integrations/readers/llama-index-readers-oxylabs/llama_index/readers/oxylabs/目录Reader底层调用方法顶层标题典型 payload 参数OxylabsAmazonSearchReaderscrape_search(**payload)Search Resultsquery、parse、domainOxylabsAmazonPricingReaderscrape_pricing(**payload)Product pricing dataquery商品 ASIN、parseOxylabsAmazonProductReaderscrape_product(**payload)ProductsqueryASIN、parseOxylabsAmazonSellersReaderscrape_sellers(**payload)Sellersquery卖家 ID、parseOxylabsAmazonBestsellersReaderscrape_bestsellers(**payload)Bestsellerssource、domain、query、render、start_page、parseOxylabsAmazonReviewsReaderscrape_reviews(**payload)ReviewsqueryASIN、parse其中各实现文件分别为 amazon_search.py、amazon_pricing.py、amazon_product.py、amazon_sellers.py、amazon_bestsellers.py、amazon_reviews.py。以亚马逊商品搜索为例from llama_index.readers.oxylabs import OxylabsAmazonSearchReader reader OxylabsAmazonSearchReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs reader.load_data( { query: headsets, domain: com, parse: True, } )4.2 Google 系列2 个 ReaderOxylabsGoogleSearchReader与OxylabsGoogleAdsReader都继承自中间层OxylabsGoogleBaseReadergoogle_base.py该中间层对 Google 搜索结果做了细粒度的分类解析。OxylabsGoogleAdsReader用于单独获取付费广告结果底层调用scrape_ads(**payload)。from llama_index.readers.oxylabs import OxylabsGoogleAdsReader reader OxylabsGoogleAdsReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs reader.load_data({query: iPhone 16, parse: True})4.3 YouTube 字幕1 个 ReaderOxylabsYoutubeTranscriptReader通过self.oxylabs_api.youtube_transcript.scrape_transcript(**payload)获取视频字幕顶层标题为YouTube video transcripts。测试用例展示了其典型参数结构from llama_index.readers.oxylabs import OxylabsYoutubeTranscriptReader reader OxylabsYoutubeTranscriptReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs reader.load_data( { query: SLoqvcnwwN4, # YouTube 视频 ID context: [ {key: language_code, value: en}, {key: transcript_origin, value: uploader_provided}, ], } )五、源码级原理数据如何变成 Document5.1 基类的统一处理管线所有 Reader 的核心逻辑集中在OxylabsBaseReaderbase.py构造阶段__init__接收username、password同时创建同步客户端RealtimeClient与异步客户端AsyncClient并附加sdk_type标识格式为oxylabs-llama-index-oxy-sdk-python/包版本 (Python 版本; 架构位数)便于服务端识别调用来源。加载阶段load_data(payload)调用子类实现的get_response(payload)拿到Response经_validate_response校验后调用_get_document_from_response生成Document。异步对应aload_data(payload)使用aget_response(payload)返回类型与同步版一致便于在 asyncio 环境中使用。每个子类只需实现get_response/aget_response两个方法即可接入新的目标站点这也是该设计可扩展性最好的体现。5.2 响应校验逻辑_validate_response基类对 Oxylabs 返回的原始响应做了严格校验读取response.raw[results]若结果不是非空列表则抛出ValueError(No results returned!)对每个结果页若content本身是列表则直接采用若content为字典优先提取其中的results字段列表或字典均可若content既不是列表也不是字典则提示请将parse参数设置为 True。这正是 README 示例中parse: True至关重要的原因——该参数让 API 返回结构化的 JSON 而非原始 HTML。5.3 JSON 转 Markdownjson_to_markdown对于 Amazon 系列与 YouTube 系列转换由工具函数json_to_markdownutils.py完成。它递归地将 JSON 结构转为 Markdown字典的每个 key 生成为对应层级的标题层级上限为 6 级######列表项生成- Item N:列表多行字符串以引用块形式呈现空列表输出- *Empty List*占位。单元测试验证了输出格式例如docs[0].text应符合# {top_level_header}\n- Item 1:\n ## key1\n value1\n\n ## key2\n value2\n的结构见 test_readers_oxylabs.py。5.4 Google 结果分类解析OxylabsGoogleBaseReaderGoogle 系列走的是另一套更精细的解析路径。OxylabsGoogleBaseReader预定义了 5 大结果分类RESULT_CATEGORIESknowledge_graph知识图谱、combined_search_result综合搜索结果、product_information商品信息、local_information本地信息、search_information搜索信息。解析时通过递归收集器_recursive_snippet_collector默认递归深度parsing_recursion_depth5把嵌套 JSON 展平为带缩进与标签的文本片段例如集成测试断言中出现的ORGANIC RESULTS ITEMS、SEARCH INFORMATION、RELATED SEARCHES ITEMS等。值得注意的细节配置include_binary_image_data: bool False默认不保留图片二进制数据相关字段如image_data、data、images数组会被替换为占位符Redacted base64 image string...避免向 LLM 上下文注入大量无意义 base64 内容excluded_result_attributes: list[str] [pos_overall]默认剔除pos_overall这类位置元数据保持文档简洁。六、payload 参数实战参考以下参数组合直接取自仓库的单元/集成测试参数化用例tests/test_readers_oxylabs.py可放心作为实际调用模板Amazon Bestsellers{source: amazon_bestsellers, domain: com, query: 120225786011, render: html, start_page: 1, parse: True}Amazon Pricing / Product / Reviews{query: B087TXHLVQ, parse: True}query 传 ASINAmazon Sellers{query: A2U55XLSPNCN01, parse: True}query 传卖家 IDAmazon Search{query: headsets, parse: True}Google Search / Ads{query: iPhone 16, parse: True}YouTube Transcript{query: video_id, context: [{key: language_code, value: en}, {key: transcript_origin, value: uploader_provided}]}Google SearchREADME 增强版额外支持geo_location如Berlin, Germany等地理参数注意事项这些 Reader 的load_data始终返回恰好一个Document的列表所有结果页被合并进同一文档这是基类load_data的实现行为单元测试通过 Mock 覆盖了全部 8 个具体 Reader 的同步与异步路径test_sync_oxylabs_readers/test_async_oxylabs_readers而 Google 系列另有需要真实凭证环境变量OXYLABS_USERNAME、OXYLABS_PASSWORD的集成测试未设置凭证时会被自动跳过。七、异步调用与常见问题7.1 异步用法所有 Reader 均支持 asyncioimport asyncio from llama_index.readers.oxylabs import OxylabsAmazonProductReader async def main(): reader OxylabsAmazonProductReader( usernameOXYLABS_USERNAME, passwordOXYLABS_PASSWORD, ) docs await reader.aload_data({query: B087TXHLVQ, parse: True}) print(docs[0].text) asyncio.run(main())7.2 常见报错与排查现象原因与处理Response Validation Error: No results returned!响应中results为空检查 query 参数或配额Result content format error, try setting parameter parse to True返回了非结构化内容请在 payload 中显式设置parse: True文档中包含Redacted base64 image string...正常行为图片二进制默认被脱敏如需原图数据可设置include_binary_image_dataTrue会增加 token 消耗集成测试被跳过未设置OXYLABS_USERNAME/OXYLABS_PASSWORD环境变量属预期行为八、总结llama-index-readers-oxylabs将商业级爬虫能力与 LlamaIndex 文档体系无缝衔接通过 base.py 的响应校验、utils.py 的 JSON-to-Markdown 转换以及 google_base.py 的分类化解析实现了一次编写、多源复用。无论是构建电商监控、SEO 研究还是视频内容检索管线只需按本文选择对应 Reader、配置凭证与 payload即可将抓取数据直接送入 LlamaIndex 的索引与查询流程。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考