LlamaIndex AzStorageBlobReader 实战从 Azure Blob 存储加载文档到 RAG 流水线【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读AzStorageBlobReader是 LlamaIndex 官方提供的 Azure Blob 存储数据连接器用于将 Azure 存储容器中的单个 blob 文件或整个目录容器拉取为 LlamaIndex 的Document对象直接接入后续索引构建、检索与问答流程。读完本文你将掌握该 Reader 的全部构造参数、三种认证方式SAS URL / 连接字符串 / Azure AD、文件级过滤与自定义解析器的用法以及其底层本地临时下载 SimpleDirectoryReader 解析的实现原理与资源级 API。一、认识 AzStorageBlobReader定位与源码结构AzStorageBlobReader位于仓库 llama-index-integrations/readers/llama-index-readers-azstorage-blob 中官方 API 参考文档 azstorage_blob.md 将其作为该模块唯一公开的成员导出。从源码 base.py 可见它同时继承三个基类BasePydanticReader基于 Pydantic 的 Reader 基类支持参数校验与 JSON 序列化ResourcesReaderMixin提供list_resources/get_resource_info/load_resource等资源级操作能力FileSystemReaderMixin提供read_file_content等文件级读取能力。模块导出入口 __init__.py 中__all__ [AzStorageBlobReader]即使用from llama_index.readers.azstorage_blob import AzStorageBlobReader即可导入。安装与版本要求按 README.md 与 pyproject.toml 声明pip install llama-index-readers-azstorage-blob运行时依赖见 pyproject.toml依赖版本范围azure-storage-blob12.19.0, 13azure-identity1.15.0, 2llama-index-core0.13.0, 0.15Python 要求 3.10。若使用 Azure AD 认证还需额外pip install azure-identity。二、构造参数详解AzStorageBlobReader的所有参数均在源码类定义中声明base.py其中container_name为必填参数类型必填说明container_namestr是Blob 所在的容器名称必须指定blobOptional[str]否要下载的单个文件 blob 名。不传则遍历容器内所有 blob。若文件位于子目录需带路径如subdirectory/input.txtname_starts_withOptional[str]否前缀过滤仅下载名称以该字符串开头的 blobincludeUnion[str, List[str], None]否追加返回数据集选项snapshots、metadata、uncommittedblobs、copy、deleted、deletedwithversions、tags、versions、immutabilitypolicy、legalholdfile_extractorDict[str, Union[str, BaseReader]]否文件扩展名到解析器的映射指定如何将特定类型文件转为文本最终传给SimpleDirectoryReaderconnection_stringOptional[str]否存储账户连接字符串账户访问密钥安全页可找到可替代 account_url credentialaccount_urlOptional[str]否存储账户 URI可携带 SAS tokencredentialOptional[Any]否认证凭据支持字符串、AzureNamedKeyCredential、AzureSasCredential、TokenCredential等若 account_url 已含 SAS token 则可省略is_remotebool否远程数据标志默认Truefile_metadata_fnCallable[[str], Dict]否接收文件名、返回 Document 元数据字典的函数默认Nonefilename_as_idbool否是否用文件名作为文档 id默认True源码字段默认值注意README 旧示例中出现过container参数名但当前源码的 Pydantic 字段为container_name测试用例 test_readers_azstorage_blob.py 也使用container_name构造实际使用时请以container_name为准。三、三种认证方式实战该 Reader 是 Azure Blob Storage Client for Python指定connection_string时走ContainerClient.from_connection_string否则走ContainerClient(account_url, container_name, credentialcredential)。1. 使用 SAS URL存储账户 SASfrom llama_index.readers.azstorage_blob import AzStorageBlobReader loader AzStorageBlobReader( container_namescrabble-dictionary, blobdictionary.txt, account_urlSAS_URL, # 可携带 SAS token 的账户 URI ) documents loader.load_data()2. 使用连接字符串下载整个容器仅提供连接字符串与容器名即可下载容器内的全部文件from llama_index.readers.azstorage_blob import AzStorageBlobReader loader AzStorageBlobReader( container_nameCONTAINER_NAME, connection_stringSTORAGE_ACCOUNT_CONNECTION_STRING, ) documents loader.load_data()3. 使用 Azure AD 凭据先安装pip install azure-identity再传入凭据对象DefaultAzureCredential为默认凭据链也可换成服务主体的ClientSecretCredential等from azure.identity import DefaultAzureCredential from llama_index.readers.azstorage_blob import AzStorageBlobReader default_credential DefaultAzureCredential() loader AzStorageBlobReader( container_namescrabble-dictionary, account_urlhttps://storage-account-name.blob.core.windows.net, credentialdefault_credential, ) documents loader.load_data()四、单文件加载与容器遍历blob参数是决定行为的关键指定blob仅下载该单一 blob。源码中_download_files_and_extract_metadata会将其包装为单元素列表[self.blob]base.py省略blob调用container_client.list_blobs(name_starts_with, include)遍历容器内全部 blobbase.py可配合name_starts_with前缀过滤和include追加数据集选项实现细粒度筛选。下载时blob 名中的/会被替换为-作为本地临时文件名base.py避免子目录路径与本地目录结构冲突。五、自定义文件解析器 file_extractor所有 blob 会被临时下载到本地目录随后统一交给SimpleDirectoryReader解析base.py。因此你可以复用 LlamaIndex 生态中任何基于扩展名映射的解析器例如覆盖 PDF 解析import llama_index file_extractor llama_index.readers.file.base.DEFAULT_FILE_READER_CLS # 覆盖/新增某类文件的解析器需传入类实例 file_extractor.update({.pdf: SimplePDFReader()}) loader AzStorageBlobReader( container_namescrabble-dictionary, blobdictionary.pdf, account_urlSAS_URL, file_extractorfile_extractor, )这一设计意味着无论 blob 中是文本、PDF、Word 还是图片只要提供对应的file_extractor都能被转成可供索引的文本内容。六、元数据提取机制AzStorageBlobReader会为每个Document自动注入来自 Azure Blob 的属性元数据。核心逻辑在_extract_blob_metadatabase.py提取字段包括元数据键来源file_nameblob 名称file_typecontent_settings.content_typefile_sizeblob 大小creation_datecreation_time格式化为%Y-%m-%dlast_modified_datelast_modified%Y-%m-%dlast_accessed_datelast_accessed_on%Y-%m-%dcontainer所属容器自定义键blob 的metadata与tags字典会被合并进元数据下载完成后load_data()会打印下载耗时统计分/秒粒度并通过_load_documents_with_metadata将上述元数据绑定到每个Documentbase.py。此外SanitizedJSONEncoderbase.py负责将datetime、bytearray等非 JSON 原生类型安全序列化确保元数据可写入存储。若需自定义元数据可传入file_metadata_fn它接收文件名并返回元数据字典未提供时使用内置的 blob 属性元数据file_metadataself.file_metadata_fn or get_metadata。七、源码级工作流程load_data 全链路load_data()的完整执行流程base.py创建tempfile.TemporaryDirectory()临时目录调用_download_files_and_extract_metadata(temp_dir)获取ContainerClient→ 确定 blob 列表单个 blob 或list_blobs遍历→ 逐个download_blob()写入临时文件同时记录每个文件的get_blob_properties()统计整体下载耗时并打印日志调用_load_documents_with_metadata(files_metadata, temp_dir)构造SimpleDirectoryReader注入file_extractor、元数据函数与filename_as_id并load_data()返回List[Document]临时目录在with块退出时自动清理不残留本地文件。整个设计可概括为远程下载到临时目录 → 本地解析 → 自动清理对上层完全透明。八、资源级 API面向 Agent 的细粒度访问得益于ResourcesReaderMixin与FileSystemReaderMixin该 Reader 还提供了不经过整目录下载的资源级接口base.py适用于 Agent 按需取数的场景list_resources()列出容器内所有 blob 名称同样支持name_starts_with与include过滤get_resource_info(resource_id)返回指定 blob 的元数据字典复用_extract_blob_metadata并将:替换为/生成file_pathNone值会被剔除load_resource(resource_id)仅下载并解析指定的单个 blob 为Document列表失败时记录日志并抛出异常read_file_content(input_file)直接以字节流返回 blob 内容stream.readall()。这些接口让上层 Agent 可以先列举资源、查询元数据再按需加载特定文件避免每次都全量下载整个容器。九、测试与可靠性验证仓库为该 Reader 提供了单元测试 test_readers_azstorage_blob.pytest_class断言AzStorageBlobReader的 MRO 中包含BaseReader确保其正确继承 Reader 体系test_serialize构造 reader 后调用reader.schema()校验 Pydantic schema 非空且包含container_name字段再通过reader.json(exclude_unsetTrue)与AzStorageBlobReader.parse_raw(json)完成序列化/反序列化往返验证配置对象可持久化、可传输。这意味着该 Reader 的配置对象天然支持保存为 JSON 后恢复可安全地写入工作流状态或配置文件。结语AzStorageBlobReader将 Azure Blob 存储接入 LlamaIndex 的成本降到了最低一个必填参数container_name加任一认证方式即可加载数据。单文件、容器遍历、前缀过滤、自定义解析器与丰富的 blob 元数据注入覆盖了从快速原型到生产级 RAG 的大多数场景而资源级 API 与 Pydantic 序列化能力又为其在 Agent 工作流与持久化配置中的复用提供了坚实基础。结合 README.md 中的完整示例与上述源码分析你可以立即在本地复现三种认证方式并将 Azure 上的文档接入自己的索引与问答系统。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LlamaIndex AzStorageBlobReader 实战：从 Azure Blob 存储加载文档到 RAG 流水线
LlamaIndex AzStorageBlobReader 实战从 Azure Blob 存储加载文档到 RAG 流水线【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读AzStorageBlobReader是 LlamaIndex 官方提供的 Azure Blob 存储数据连接器用于将 Azure 存储容器中的单个 blob 文件或整个目录容器拉取为 LlamaIndex 的Document对象直接接入后续索引构建、检索与问答流程。读完本文你将掌握该 Reader 的全部构造参数、三种认证方式SAS URL / 连接字符串 / Azure AD、文件级过滤与自定义解析器的用法以及其底层本地临时下载 SimpleDirectoryReader 解析的实现原理与资源级 API。一、认识 AzStorageBlobReader定位与源码结构AzStorageBlobReader位于仓库 llama-index-integrations/readers/llama-index-readers-azstorage-blob 中官方 API 参考文档 azstorage_blob.md 将其作为该模块唯一公开的成员导出。从源码 base.py 可见它同时继承三个基类BasePydanticReader基于 Pydantic 的 Reader 基类支持参数校验与 JSON 序列化ResourcesReaderMixin提供list_resources/get_resource_info/load_resource等资源级操作能力FileSystemReaderMixin提供read_file_content等文件级读取能力。模块导出入口 __init__.py 中__all__ [AzStorageBlobReader]即使用from llama_index.readers.azstorage_blob import AzStorageBlobReader即可导入。安装与版本要求按 README.md 与 pyproject.toml 声明pip install llama-index-readers-azstorage-blob运行时依赖见 pyproject.toml依赖版本范围azure-storage-blob12.19.0, 13azure-identity1.15.0, 2llama-index-core0.13.0, 0.15Python 要求 3.10。若使用 Azure AD 认证还需额外pip install azure-identity。二、构造参数详解AzStorageBlobReader的所有参数均在源码类定义中声明base.py其中container_name为必填参数类型必填说明container_namestr是Blob 所在的容器名称必须指定blobOptional[str]否要下载的单个文件 blob 名。不传则遍历容器内所有 blob。若文件位于子目录需带路径如subdirectory/input.txtname_starts_withOptional[str]否前缀过滤仅下载名称以该字符串开头的 blobincludeUnion[str, List[str], None]否追加返回数据集选项snapshots、metadata、uncommittedblobs、copy、deleted、deletedwithversions、tags、versions、immutabilitypolicy、legalholdfile_extractorDict[str, Union[str, BaseReader]]否文件扩展名到解析器的映射指定如何将特定类型文件转为文本最终传给SimpleDirectoryReaderconnection_stringOptional[str]否存储账户连接字符串账户访问密钥安全页可找到可替代 account_url credentialaccount_urlOptional[str]否存储账户 URI可携带 SAS tokencredentialOptional[Any]否认证凭据支持字符串、AzureNamedKeyCredential、AzureSasCredential、TokenCredential等若 account_url 已含 SAS token 则可省略is_remotebool否远程数据标志默认Truefile_metadata_fnCallable[[str], Dict]否接收文件名、返回 Document 元数据字典的函数默认Nonefilename_as_idbool否是否用文件名作为文档 id默认True源码字段默认值注意README 旧示例中出现过container参数名但当前源码的 Pydantic 字段为container_name测试用例 test_readers_azstorage_blob.py 也使用container_name构造实际使用时请以container_name为准。三、三种认证方式实战该 Reader 是 Azure Blob Storage Client for Python指定connection_string时走ContainerClient.from_connection_string否则走ContainerClient(account_url, container_name, credentialcredential)。1. 使用 SAS URL存储账户 SASfrom llama_index.readers.azstorage_blob import AzStorageBlobReader loader AzStorageBlobReader( container_namescrabble-dictionary, blobdictionary.txt, account_urlSAS_URL, # 可携带 SAS token 的账户 URI ) documents loader.load_data()2. 使用连接字符串下载整个容器仅提供连接字符串与容器名即可下载容器内的全部文件from llama_index.readers.azstorage_blob import AzStorageBlobReader loader AzStorageBlobReader( container_nameCONTAINER_NAME, connection_stringSTORAGE_ACCOUNT_CONNECTION_STRING, ) documents loader.load_data()3. 使用 Azure AD 凭据先安装pip install azure-identity再传入凭据对象DefaultAzureCredential为默认凭据链也可换成服务主体的ClientSecretCredential等from azure.identity import DefaultAzureCredential from llama_index.readers.azstorage_blob import AzStorageBlobReader default_credential DefaultAzureCredential() loader AzStorageBlobReader( container_namescrabble-dictionary, account_urlhttps://storage-account-name.blob.core.windows.net, credentialdefault_credential, ) documents loader.load_data()四、单文件加载与容器遍历blob参数是决定行为的关键指定blob仅下载该单一 blob。源码中_download_files_and_extract_metadata会将其包装为单元素列表[self.blob]base.py省略blob调用container_client.list_blobs(name_starts_with, include)遍历容器内全部 blobbase.py可配合name_starts_with前缀过滤和include追加数据集选项实现细粒度筛选。下载时blob 名中的/会被替换为-作为本地临时文件名base.py避免子目录路径与本地目录结构冲突。五、自定义文件解析器 file_extractor所有 blob 会被临时下载到本地目录随后统一交给SimpleDirectoryReader解析base.py。因此你可以复用 LlamaIndex 生态中任何基于扩展名映射的解析器例如覆盖 PDF 解析import llama_index file_extractor llama_index.readers.file.base.DEFAULT_FILE_READER_CLS # 覆盖/新增某类文件的解析器需传入类实例 file_extractor.update({.pdf: SimplePDFReader()}) loader AzStorageBlobReader( container_namescrabble-dictionary, blobdictionary.pdf, account_urlSAS_URL, file_extractorfile_extractor, )这一设计意味着无论 blob 中是文本、PDF、Word 还是图片只要提供对应的file_extractor都能被转成可供索引的文本内容。六、元数据提取机制AzStorageBlobReader会为每个Document自动注入来自 Azure Blob 的属性元数据。核心逻辑在_extract_blob_metadatabase.py提取字段包括元数据键来源file_nameblob 名称file_typecontent_settings.content_typefile_sizeblob 大小creation_datecreation_time格式化为%Y-%m-%dlast_modified_datelast_modified%Y-%m-%dlast_accessed_datelast_accessed_on%Y-%m-%dcontainer所属容器自定义键blob 的metadata与tags字典会被合并进元数据下载完成后load_data()会打印下载耗时统计分/秒粒度并通过_load_documents_with_metadata将上述元数据绑定到每个Documentbase.py。此外SanitizedJSONEncoderbase.py负责将datetime、bytearray等非 JSON 原生类型安全序列化确保元数据可写入存储。若需自定义元数据可传入file_metadata_fn它接收文件名并返回元数据字典未提供时使用内置的 blob 属性元数据file_metadataself.file_metadata_fn or get_metadata。七、源码级工作流程load_data 全链路load_data()的完整执行流程base.py创建tempfile.TemporaryDirectory()临时目录调用_download_files_and_extract_metadata(temp_dir)获取ContainerClient→ 确定 blob 列表单个 blob 或list_blobs遍历→ 逐个download_blob()写入临时文件同时记录每个文件的get_blob_properties()统计整体下载耗时并打印日志调用_load_documents_with_metadata(files_metadata, temp_dir)构造SimpleDirectoryReader注入file_extractor、元数据函数与filename_as_id并load_data()返回List[Document]临时目录在with块退出时自动清理不残留本地文件。整个设计可概括为远程下载到临时目录 → 本地解析 → 自动清理对上层完全透明。八、资源级 API面向 Agent 的细粒度访问得益于ResourcesReaderMixin与FileSystemReaderMixin该 Reader 还提供了不经过整目录下载的资源级接口base.py适用于 Agent 按需取数的场景list_resources()列出容器内所有 blob 名称同样支持name_starts_with与include过滤get_resource_info(resource_id)返回指定 blob 的元数据字典复用_extract_blob_metadata并将:替换为/生成file_pathNone值会被剔除load_resource(resource_id)仅下载并解析指定的单个 blob 为Document列表失败时记录日志并抛出异常read_file_content(input_file)直接以字节流返回 blob 内容stream.readall()。这些接口让上层 Agent 可以先列举资源、查询元数据再按需加载特定文件避免每次都全量下载整个容器。九、测试与可靠性验证仓库为该 Reader 提供了单元测试 test_readers_azstorage_blob.pytest_class断言AzStorageBlobReader的 MRO 中包含BaseReader确保其正确继承 Reader 体系test_serialize构造 reader 后调用reader.schema()校验 Pydantic schema 非空且包含container_name字段再通过reader.json(exclude_unsetTrue)与AzStorageBlobReader.parse_raw(json)完成序列化/反序列化往返验证配置对象可持久化、可传输。这意味着该 Reader 的配置对象天然支持保存为 JSON 后恢复可安全地写入工作流状态或配置文件。结语AzStorageBlobReader将 Azure Blob 存储接入 LlamaIndex 的成本降到了最低一个必填参数container_name加任一认证方式即可加载数据。单文件、容器遍历、前缀过滤、自定义解析器与丰富的 blob 元数据注入覆盖了从快速原型到生产级 RAG 的大多数场景而资源级 API 与 Pydantic 序列化能力又为其在 Agent 工作流与持久化配置中的复用提供了坚实基础。结合 README.md 中的完整示例与上述源码分析你可以立即在本地复现三种认证方式并将 Azure 上的文档接入自己的索引与问答系统。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考