LangChain4j Azure Blob Storage 文档加载器AzureBlobStorageDocumentLoader实战指南【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j本文围绕 LangChain4j 官方集成的langchain4j-document-loader-azure-storage-blob模块系统讲解如何将 Azure Blob Storage 中的对象Blob加载为可被 LLM 应用消费的Document。你将掌握依赖引入、客户端构建、单文档与批量含前缀过滤加载的完整 API 用法、自动写入的元数据字段以及结合官方测试用例的本地与云端验证方法从而在 RAG、文档解析等场景中快速打通 Azure 存储到 LangChain4j 的数据链路。模块概述与适用场景Azure Blob Storage 是微软 Azure 提供的海量对象存储服务广泛用于存放文档、日志、备份等非结构化数据。LangChain4j 以独立集成模块 langchain4j-document-loader-azure-storage-blob 的形式提供支持其核心类是AzureBlobStorageDocumentLoader见 AzureBlobStorageDocumentLoader.java把从容器读取对象与用DocumentParser解析文本两个环节解耦它只负责从 Azure 拉取二进制内容并包装成DocumentSource具体如何把字节流解析成文本纯文本、PDF、Markdown、HTML 等由你传入的DocumentParser决定解析结果统一落成Document对象可直接进入 LangChain4j 的 RAG 管道切分、向量化、入库检索。引入 Maven 依赖在项目的pom.xml中添加如下依赖版本号以官方发布为准示例为文档中给出的1.20.0-beta30dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-document-loader-azure-storage-blob/artifactId version1.20.0-beta30/version /dependency从该模块的 pom.xml 可以看出它内部传递依赖了以下关键库无需你额外声明依赖作用langchain4j-core提供Document、DocumentParser、DocumentSource等核心抽象azure-storage-blobAzure Blob 官方 Java SDK负责与存储账号通信azure-storage-common、azure-coreAzure SDK 基础设施共享密钥、管道等azure-identity支持托管身份 / Azure AD 等基于身份的认证方式jackson-dataformat-xmlAzure Blob 服务响应中的 XML 解析slf4j-api日志记录构建 BlobServiceClientAzureBlobStorageDocumentLoader的构造函数接收一个 Azure SDK 的BlobServiceClientensureNotNull校验非空。构建方式取决于你的认证方案方式一存储账号共享密钥Storage Shared Keyimport com.azure.storage.blob.BlobServiceClient; import com.azure.storage.blob.BlobServiceClientBuilder; import com.azure.storage.common.StorageSharedKeyCredential; String accountName System.getenv(AZURE_STORAGE_ACCOUNT_NAME); String accountKey System.getenv(AZURE_STORAGE_ACCOUNT_KEY); BlobServiceClient blobServiceClient new BlobServiceClientBuilder() .endpoint(String.format(https://%s.blob.core.windows.net/, accountName)) .credential(new StorageSharedKeyCredential(accountName, accountKey)) .buildClient();这正是官方集成测试 AzureBlobStorageDocumentLoaderIT.java 中的用法测试类通过EnabledIfEnvironmentVariable(named AZURE_STORAGE_ACCOUNT_NAME, matches .)控制仅在设置了对应环境变量时才运行。方式二连接字符串Connection String本地开发或使用 Azurite 模拟器时更为方便BlobServiceClient blobServiceClient new BlobServiceClientBuilder() .connectionString(DefaultEndpointsProtocolhttp;AccountNamedevstoreaccount1;AccountKey...;BlobEndpointhttp://localhost:10000/devstoreaccount1;) .buildClient();方式三Azure Identity托管身份 / DefaultAzureCredential依赖中已包含azure-identity生产环境可配合DefaultAzureCredential、Workload Identity 等身份认证避免在代码中硬编码密钥。加载单个文档loadDocumentloadDocument(String containerName, String blobName, DocumentParser parser)用于加载容器内指定的单个 Blob。从源码AzureBlobStorageDocumentLoader.java#L30-L38可以看到其内部执行了三个步骤blobServiceClient.getBlobContainerClient(containerName).getBlobClient(blobName)定位目标 BlobblobClient.getProperties()读取属性、openInputStream()打开输入流将两者包装为AzureBlobStorageSource后交给DocumentLoader.load(source, parser)完成解析。典型用法import dev.langchain4j.data.document.Document; import dev.langchain4j.data.document.DocumentParser; import dev.langchain4j.data.document.loader.azure.storage.blob.AzureBlobStorageDocumentLoader; import dev.langchain4j.data.document.parser.TextDocumentParser; AzureBlobStorageDocumentLoader loader new AzureBlobStorageDocumentLoader(blobServiceClient); DocumentParser parser new TextDocumentParser(); Document document loader.loadDocument(test-container, test-file.txt, parser); System.out.println(document.text());官方集成测试中should_load_single_document验证加载出的document.text()与上传内容一致且元数据共 4 个键。批量加载整个容器loadDocumentsloadDocuments(String containerName, DocumentParser parser)会列出容器内的所有 Blob并逐一加载返回ListDocument。源码实现有两个值得注意的行为AzureBlobStorageDocumentLoader.java#L48-L93失败跳过单个 Blob 加载抛异常时不会中断整体流程而是计数并记录warn日志后继续处理下一个汇总统计若存在失败项会在结束时输出Loaded X of Y documents ... Skipped Z that failed to load.的警告日志。ListDocument documents loader.loadDocuments(test-container, parser); // 注意Azure 列出的顺序并不保证稳定测试中也观察到 // test-directory/test-file-2.txt 排在 test-file.txt 之前按前缀过滤加载loadDocuments(container, prefix, parser)第三个重载loadDocuments(String containerName, String prefix, DocumentParser parser)允许只加载名字以指定前缀开头的 Blob// 只加载 test-directory/ 下的对象Blob 的目录本质上只是名称前缀 ListDocument documents loader.loadDocuments(test-container, test-directory/, parser);实现上它通过new ListBlobsOptions().setPrefix(prefix)把前缀传给 Azure 服务端过滤prefix传null等价于加载全部。本地 Azurite 集成测试 LocalAzureBlobStorageDocumentLoaderIT.java 中覆盖了两种边界场景前缀能匹配到对象时只返回匹配项should_load_documents_with_prefix容器中含test-file.txt与test-directory/test-file-2.txt前缀test-directory/只返回 1 个前缀匹配不到任何对象时返回空列表而非报错should_return_empty_list_when_prefix_matches_no_blobs。利用这一特性可以按业务目录、日期目录等命名规范做定向加载避免全量扫描。自动写入的元数据字段加载产生的每个Document都带有 4 个元数据键由 AzureBlobStorageSource.java 的metadata()方法生成元数据键说明示例值source该 Blob 的可访问 URLhttps://account.blob.core.windows.net/container/blobazure_storage_blob_creation_time对象创建时间2026-01-01T00:00:00Zazure_storage_blob_last_modified对象最后修改时间2026-01-01T00:00:00Zazure_storage_blob_content_length对象大小字节13这些元数据在 RAG 场景中非常有用source可在回答中作为引用出处返回时间字段可用于基于时间的文档过滤内容长度可用于体积统计。关于元数据合并有一条值得注意的语义DocumentLoader.load见 DocumentLoader.java在解析完成后会把source.metadata()合并进Document.metadata()当解析器与数据源产生同名键冲突时数据源的值胜出解析器的值被丢弃并输出告警日志。因此若你的自定义DocumentParser恰好也设置了上述键需要在解析器中主动移除以避免冲突。解析器选择与后续链路本模块并不关心文件格式——PDF、DOCX、Markdown、纯文本等都可以通过不同的DocumentParser组合加载TextDocumentParser纯文本解析位于 langchain4j 模块测试与示例中均使用它其他格式可配合 Apache PDFBox、Apache POI、Markdown 等文档解析器模块或使用DocumentLoader.load后接入 LangChain4j 的文档转换器与向量库做 RAG。本地与云端测试验证官方测试给出了两种可复现的验证路径1. 真实 Azure 账号集成测试AzureBlobStorageDocumentLoaderIT.java前提设置环境变量AZURE_STORAGE_ACCOUNT_NAME与AZURE_STORAGE_ACCOUNT_KEY流程BeforeAll创建容器test-container并上传test-file.txt与test-directory/test-file-2.txt两个 Blob测试结束后删除容器覆盖单文档加载、批量加载、元数据断言source以/test-file.txt结尾、共 4 个键。2. Azurite 本地模拟器测试LocalAzureBlobStorageDocumentLoaderIT.java基于 Testcontainers 自动拉起mcr.microsoft.com/azure-storage/azurite:latest容器Blob 端口10000并带--skipApiVersionCheck参数绕过版本检查通过连接字符串devstoreaccount1账号 固定开发密钥构建客户端无需任何真实 Azure 资源即可运行全部测试额外覆盖前缀过滤成功、前缀无匹配返回空列表两个场景。对开发调试而言本地 Azurite 方案可以零成本地把加载链路完整跑通是接入前最推荐的验证方式。小结AzureBlobStorageDocumentLoader以极小的 API 面一个构造器、两个加载方法族完成了 Azure Blob Storage 到 LangChain4jDocument的对接单对象加载按需取数批量加载自动跳过失败项并附带完整统计日志前缀参数把过滤下沉到 Azure 服务端适合按目录/命名规则定向拉取每次加载自动注入source、创建时间、修改时间、大小 4 项元数据为 RAG 引用溯源与过滤提供基础云端集成测试与 Azurite 本地测试双轨覆盖便于在任何环境验证集成行为。配合适当的DocumentParser即可把 Azure 上的文档资产无缝接入 LangChain4j 的 RAG、Agent 等上层能力。【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考