
LlamaIndex Box 读取器全解析BoxReader 家族四种文件加载与 AI 提取方案【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读llama-index-readers-box是 LlamaIndex 官方提供的 Box 云存储集成包它将 Box 上的文件文档、表格、PPT、PDF 等无缝接入 LlamaIndex 的 Document / Index 管线。本文基于该包的 API 参考文档围绕BoxReader、BoxReaderAIExtract、BoxReaderAIPrompt、BoxReaderTextExtraction四个核心类结合包内源码、官方示例与测试系统讲解如何在 LlamaIndex 应用中读取 Box 文件、提取纯文本、调用 Box AI 完成结构化数据抽取与自定义问答并掌握基于 ResourcesReaderMixin 的资源发现与搜索能力。读完本文你将能够独立完成从 Box 认证、文件加载到索引构建的完整链路。一、模块定位一个包四种读取范式API 参考文档 readers/box.md 声明了四个成员类它们全部继承自抽象基类BoxReaderBase区别在于文件内容的获取方式不同类内容来源典型场景BoxReader下载文件到本地临时目录经SimpleDirectoryReader解析通用文件加载支持自定义文件解析器BoxReaderTextExtractionBox 服务端的extracted_text文本表示快速获取纯文本无需本地解析BoxReaderAIExtractBox AI Extractcreate_ai_extract按 JSON Schema 抽取结构化字段BoxReaderAIPromptBox AI Askcreate_ai_ask自定义 Prompt 问答/摘要四个类统一接收BoxClient来自官方box-sdk-gen构造时会在 box_api.py 中通过add_extra_header_to_box_client自动附加x-box-ai-library: llama-index请求头方便 Box 侧识别流量来源。二、安装与 Box 客户端认证2.1 安装包发布名为llama-index-readers-box其 pyproject.toml 声明了两个运行时依赖box-sdk-gen1.5.0Box 官方生成式 SDK提供BoxClient、BoxCCGAuth等llama-index-core0.13.0,0.15LlamaIndex 核心库。安装命令pip install llama-index-readers-box要求 Python3.10,4.0。2.2 创建 BoxClientCCG 认证所有 Reader 都要求传入已认证的BoxClient。官方示例 examples/box_reader.py 演示了使用客户端凭证授权CCG的方式import os import dotenv from box_sdk_gen import CCGConfig, BoxCCGAuth, BoxClient def get_box_client() - BoxClient: dotenv.load_dotenv() client_id os.getenv(BOX_CLIENT_ID, YOUR_BOX_CLIENT_ID) client_secret os.getenv(BOX_CLIENT_SECRET, YOUR_BOX_CLIENT_SECRET) enterprise_id os.getenv(BOX_ENTERPRISE_ID, YOUR_BOX_ENTERPRISE_ID) ccg_user_id os.getenv(BOX_USER_ID) config CCGConfig( client_idclient_id, client_secretclient_secret, enterprise_identerprise_id, user_idccg_user_id, ) auth BoxCCGAuth(config) if config.user_id: auth.with_user_subject(config.user_id) return BoxClient(auth)关键点BOX_CLIENT_ID/BOX_CLIENT_SECRET/BOX_ENTERPRISE_ID来自 Box 开发者控制台的 OAuth 应用配置可选设置BOX_USER_ID并调用auth.with_user_subject(config.user_id)以指定用户身份访问其文件默认以企业服务账号访问每次load_data前Reader 都会调用 box_check_connection内部执行box_client.users.get_user_me()做连通性校验认证失败会抛出BoxAPIError。测试代码 tests/conftest.py 与 tests/test_readers_box_jwt.py 还覆盖了 JWT 认证路径说明包同时兼容 JWT 与 CCG 两种凭证方式。三、BoxReader通用文件读取器BoxReader是四者中最通用的入口定义于 BoxReader/base.py。3.1 构造参数BoxReader( box_client: BoxClient, file_extractor: Optional[Dict[str, Union[str, BaseReader]]] None, )box_client已认证的 Box 客户端必填file_extractor可选映射文件扩展名或 MIME 类型 → 自定义解析器。值可以是函数字符串也可以是BaseReader子类。该参数最终透传给SimpleDirectoryReader用于处理 Box 原生解析器不支持的格式。3.2 load_data 参数与优先级def load_data( self, folder_id: Optional[str] None, file_ids: Optional[List[str]] None, is_recursive: bool False, ) - List[Document]file_ids指定文件 ID 列表一旦提供folder_id被忽略源码注释明确说明 If provided, folder_id is ignoredfolder_id指定文件夹 ID配合is_recursiveTrue可递归收集子文件夹内所有文件内部通过 get_box_folder_files_details 遍历get_folder_items(...).entries仅收集type file的条目遇到子文件夹时根据is_recursive决定是否深入。3.3 底层流程临时目录 SimpleDirectoryReaderBoxReader.load_data的完整调用链如下BoxReader/base.pybox_check_connection校验连接按file_ids或folder_id收集List[File]创建tempfile.TemporaryDirectory()调用_download_files将每个文件经 download_file_by_id内部使用box_client.downloads.download_file(id)流式下载保存到本地路径并把路径写回file.downloaded_file_path为每个文件生成Box 元数据见第六节以文件名 → 元数据字典形式传给SimpleDirectoryReader(file_metadata...)将file_extractor一并传给SimpleDirectoryReader并调用load_data()得到最终的List[Document]。from llama_index.readers.box import BoxReader reader BoxReader(box_clientbox_client) docs reader.load_data(file_ids[1584054722303])示例 examples/box_reader.py 展示了读取单个发票文件后从doc.extra_info还原File对象并打印File ID / Name / Size / Text前 100 字符的用法。对应测试见 tests/test_readers_box_reader.py。四、BoxReaderTextExtraction服务端纯文本提取BoxReaderTextExtractionBoxReaderTextExtraction/base.py不在本地解析文件而是直接请求 Box 服务端生成的extracted_text表示from llama_index.readers.box import BoxReaderTextExtraction reader BoxReaderTextExtraction(box_clientbox_client) docs reader.load_data(file_ids[1514587167701])4.1 实现要点load_data(file_ids, folder_id, is_recursive)参数语义与BoxReader完全一致核心函数 get_text_representation以x_rep_hints[extracted_text]重新拉取文件详情读取representations字段若extracted_text表示状态为none尚未生成会先请求其info.url触发文本生成拼接content.url_template得到下载地址经内部_do_request携带 Bearer Token 下载纯文本token_limit默认 10000下载内容会被截断raw_content[:token_limit]注意超长文档会丢失尾部内容无可用表示的条目会被跳过continue不会产生空文档。4.2 输出每个Document.text为提取的纯文本元数据仍来自 Box 文件信息。该方案适合不需要本地解析库的场景例如将提取文本直接送入 LLM 或 embedding 流程。五、BoxReaderAIExtract结构化数据抽取BoxReaderAIExtractBoxReaderAIExtraction/base.py调用 Box AI 的 Extract 能力将非结构化文件转换为结构化字段适合发票、采购订单等单据处理。5.1 用法from llama_index.readers.box import BoxReaderAIExtract reader BoxReaderAIExtract(box_clientbox_client) docs reader.load_data( file_ids[1517629086517], ai_prompt{doc_type,date,total,vendor,invoice_number,purchase_order_number}, )ai_prompt为必填建议传入描述期望输出结构的 JSON Schema 字符串如示例所示同样支持folder_idis_recursive批量处理整个文件夹示例中即以采购订单文件夹 is_recursiveTrue演示每个文件独立调用一次 get_files_ai_extract_data内部使用box_client.ai.create_ai_extract(prompt..., items[AiItemBase(file.id)])结果写入Documentdoc.text file.ai_responsedoc.metadata[ai_prompt]记录所用提示词doc.metadata[ai_response]记录抽取结果。该路径要求 Box 账号具备 AI 功能权限调用失败会抛出BoxAPIError。对应测试见 tests/test_readers_box_ai_extract.py。六、BoxReaderAIPrompt自定义 AI 问答与摘要BoxReaderAIPromptBoxReaderAIPrompt/base.py与BoxReaderAIExtract类似但走Box AI Ask接口prompt 更自由适合摘要、问答、要点提取等。6.1 用法与关键参数from llama_index.readers.box import BoxReaderAIPrompt reader BoxReaderAIPrompt(box_clientbox_client) docs reader.load_data( file_ids[1514587167701], ai_promptsummarize this document, individual_document_promptTrue, )individual_document_prompt是最值得关注的控制开关box_api.pyTrue默认使用CreateAiAskMode.SINGLE_ITEM_QA对每个文件单独发起一次 AI Ask输出按文件独立False使用CreateAiAskMode.MULTIPLE_ITEM_QA将所有文件作为共同上下文一次调用得到综合回答并把同一份回答写入每个文件对应的 Document。无论哪种模式ai_prompt与ai_response都会写入每个 Document 的 metadata。测试覆盖见 tests/test_readers_box_ai_prompt.py。七、共享基类资源发现、搜索与元数据模型四个 Reader 均继承BoxReaderBaseBoxReader/base.py后者实现ResourcesReaderMixin与FileSystemReaderMixin因此所有 Reader 都具备资源管理能力可直接配合 LlamaIndex 的通用资源接口使用方法作用关键参数list_resources(folder_id, file_ids, is_recursive)列出文件 ID 列表file_ids优先于folder_idget_resource_info(box_file_id)返回单个文件的详情字典内部调用get_box_files_details后to_dict()load_resource(box_file_id)按文件 ID 加载文档BoxReaderAIExtract/BoxReaderAIPrompt需额外传ai_prompt—read_file_content(input_file)按文件名即 Box 文件 ID下载文件内容返回bytes供FileSystemReaderMixin使用search_resources(...)全文搜索文件返回匹配文件 ID见下方参数search_resources_by_metadata(from_, ancestor_folder_id, ...)按 Box 元数据模板搜索需指定元数据模板 key 与祖先文件夹7.1 search_resources 完整参数search_resources透传 Boxsearch_for_content的全部过滤条件BoxReader/base.pyquery搜索关键词scope搜索范围SearchForContentScope如企业内或指定内容file_extensions按扩展名过滤created_at_range/updated_at_range创建/更新时间区间size_range文件大小区间owner_user_ids/recent_updater_user_ids按所有者/最近更新者过滤ancestor_folder_ids限定在指定文件夹族内搜索content_types内容类型SearchForContentContentTypeslimit/offset分页控制。底层实现box_api.py强制typeFILE且仅请求fields[id]返回结果只含文件 ID。搜索失败时返回空列表而非抛错。7.2 元数据模型文件元数据由 box_llama_adaptors.py 中的box_file_to_llama_document_metadata生成每个 Document 的metadata包含box_file_id、name、type、size、sha_1、etag、sequence_idpath_collection文件夹路径由各级目录名以/拼接created_at/modified_at/content_created_at/content_modified_atISO 格式时间戳trashed_at/purged_at可能为Nonecreated_by/modified_by/owned_by格式为id,name,loginparent父文件夹 IDitem_status如active等。同时Document.extra_info保存 Box SDKFile.to_dict()的完整原始数据。这一设计让下游既能拿到结构化 metadata 快速过滤又能通过File.from_dict(doc.extra_info)还原完整文件对象示例中的print_docs即如此使用。八、实战小结如何选择与组合通用建索引优先BoxReader配合file_extractor处理特殊格式其本地解析能力覆盖最广PDF、Office、JSON、CSV 等均交给SimpleDirectoryReader生态。纯文本快速通道BoxReaderTextExtraction省去下载与本地解析注意token_limit截断与无文本表示文件的静默跳过。字段级结构化BoxReaderAIExtract适合发票/PO 抽取prompt 用 JSON Schema 描述目标字段。自由问答/摘要BoxReaderAIPrompt用individual_document_prompt切换逐文件问答与多文件综合问答。资源管理任意 Reader 都可调用list_resources/search_resources/search_resources_by_metadata先定位文件再按 ID 加载避免一次性拉取整个文件夹。进一步验证可运行 examples/box_reader.py需配置.env与示例文件 ID并参考 tests 下的五组测试了解各 Reader 的边界行为认证方式、AI 响应、文本表示、文件与文件夹加载等。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考