Cloudflare Workers AI 集成指南：用 LangChain4j 在 JVM 上调用 Workers AI 大模型

Cloudflare Workers AI 集成指南用 LangChain4j 在 JVM 上调用 Workers AI 大模型【免费下载链接】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/langchain4jCloudflare Workers AI 提供了运行在全球边缘网络上的推理服务而 LangChain4j 的langchain4j-workers-ai模块以统一的ChatModel/LanguageModel接口封装了 Workers AI 的 REST API使 Java 开发者无需关心底层 HTTP 细节即可在 JVM 应用中接入 Llama、Mistral、Gemma 等开源模型。读完本文你将掌握如何引入依赖、配置账号凭证、构建并调用WorkersAiChatModel与WorkersAiLanguageModel以及理解其底层请求链路与能力边界。模块概览与定位langchain4j-workers-ai是 LangChain4j 官方维护的 Cloudflare Workers AI 集成模块位于仓库 langchain4j-workers-ai/ 目录下。它通过 LangChain4j 统一抽象的dev.langchain4j.model.chat.ChatModel和dev.langchain4j.model.language.LanguageModel接口将 Workers AI 的「单次文本补全 / 多轮对话补全」能力标准化使得上层应用可以像使用其他大模型提供商一样切换后端而不需要改写业务代码。从模块的 pom.xml 可以看出它仅依赖langchain4j-core、langchain4j-http-client以及运行时使用的langchain4j-http-client-jdk整体非常轻量JSON 序列化依赖jackson-annotations。这意味着该集成专注解决「调用 Workers AI 文本类模型」这一件事不包含向量存储、Agent 等额外包袱。添加 Maven 依赖在pom.xml中引入如下依赖版本号以你实际使用的发布版本为准dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-workers-ai/artifactId version1.20.0-beta30/version /dependency说明本文所述版本为当前文档记录版本仓库中该模块的父 POM 当前为1.21.0-beta31-SNAPSHOT正式发布时请以 Maven Central 上的最新稳定/测试版本替换。支持的 API 与功能边界文档明确列出本模块暴露的两大入口WorkersAiChatModel—— 面向多轮对话场景实现ChatModel接口WorkersAiLanguageModel—— 面向单轮文本补全场景实现LanguageModel接口。需要特别注意的是该模块不包含流式Streaming支持、Tool Calling 与结构化输出支持。从 WorkersAiChatModel.java 的实现可见chat()方法会通过ChatRequestValidationUtils对toolSpecifications、toolChoice、responseFormat等参数做校验并抛出不支持异常测试用例 WorkersAiChatModelIT.java 也验证了传入ToolSpecification会抛出UnsupportedOperationException。因此在设计基于 Workers AI 的应用时应避免依赖函数调用与 JSON Schema 输出能力。前置条件账号凭证调用 Workers AI 需要两项凭证均由 Cloudflare 控制台提供凭证用途获取位置accountId账号标识路由请求到指定账号下的 AI 运行服务Cloudflare Dashboard 的账户页面apiTokenAPI 令牌请求鉴权以Bearer头携带Cloudflare 账户 API Token 页面需授予 Workers AI 相关权限从 AbstractWorkersAIModel.java 的源码可以看到构造模型时会对三个参数逐一做非空校验ensureNotEmpty任何一项缺失都会在构建阶段直接报错而不是延迟到请求时才失败。使用 WorkersAiChatModel 实现多轮对话WorkersAiChatModel面向 chat completion 端点支持system、user、ai三种角色消息的组装并兼容 LangChain4j 的ToolExecutionResultMessage仅限文本内容。构建模型实例推荐使用流式 Builder 方式构建import dev.langchain4j.model.workersai.WorkersAiChatModel; WorkersAiChatModel chatModel WorkersAiChatModel.builder() .modelName(WorkersAiChatModelName.LLAMA2_7B_FULL.toString()) .accountId(System.getenv(WORKERS_AI_ACCOUNT_ID)) .apiToken(System.getenv(WORKERS_AI_API_KEY)) .build();Builder 支持的关键配置项对应 WorkersAiChatModel.javaaccountId(String)Cloudflare 账号标识必填apiToken(String)API 令牌必填modelName(String)模型名称推荐使用WorkersAiChatModelName枚举也支持直接传字符串如cf/meta/llama-3-8b-instructhttpClientBuilder(HttpClientBuilder)可选自定义底层 HTTP 客户端如替换为 OkHttp/Apache 实现。此外还有便捷构造函数new WorkersAiChatModel(accountId, modelName, apiToken)可供直接使用。发起对话请求import dev.langchain4j.data.message.ChatMessage; import dev.langchain4j.data.message.SystemMessage; import dev.langchain4j.data.message.UserMessage; import dev.langchain4j.model.chat.response.ChatResponse; import java.util.ArrayList; import java.util.List; ListChatMessage conversation new ArrayList(); conversation.add(SystemMessage.from(You are a helpful assistant.)); conversation.add(UserMessage.from(What is the capital of France?)); ChatResponse response chatModel.chat(conversation); System.out.println(response.aiMessage().text());chat()返回的ChatResponse中包含aiMessage()模型回复文本、metadata()内含 token 用量与finishReason()如STOP。测试用例 WorkersAiChatModelIT.java 展示了两种典型断言直接单轮提问后校验回复非空且finishReason为STOP携带 system 指令的多轮上下文对话则验证模型严格遵循指令输出如返回PARIS。底层消息映射与请求链路WorkersAiChatModel内部会把 LangChain4j 的ChatMessage映射为 Workers AI 的Message角色取自 WorkersAiChatCompletionRequest.MessageRole即system/ai/user再通过WorkersAiClient.generateChat()发送。底层 WorkersAiClient.java 实际构造的请求为POST https://api.cloudflare.com/client/v4/accounts/{accountId}/ai/run/{modelName} Headers: Content-Type: application/json Authorization: Bearer {apiToken} Body: {messages: [{role: ..., content: ...}]}请求超时默认取 30 秒连接与读取均为 30 秒可通过WorkersAiClient.Builder.timeout(Duration)调整这一设计兼顾了图片生成等耗时场景。使用 WorkersAiLanguageModel 实现单轮文本补全当只需要「提示词 → 文本」的简单补全无需多轮记忆时可用WorkersAiLanguageModel其接口更精简import dev.langchain4j.model.workersai.WorkersAiLanguageModel; WorkersAiLanguageModel languageModel WorkersAiLanguageModel.builder() .modelName(WorkersAiChatModelName.MISTRAL_7B_INSTRUCT.toString()) .accountId(System.getenv(WORKERS_AI_ACCOUNT_ID)) .apiToken(System.getenv(WORKERS_AI_API_KEY)) .build(); String answer languageModel.generate(Tell me a joke about the cloud); System.out.println(answer);对应 WorkersAiLanguageModel.java 的实现generate(String prompt)会构造WorkersAiTextCompletionRequest并调用文本补全端点返回的ResponseString中content()即为模型输出文本。测试用例 WorkersAiLanguageModelIT.java 验证了该路径可用。可用的模型清单WorkersAiChatModelName枚举WorkersAiChatModelName.java预置了大量模型标识均以cf/或hf/前缀表示 Cloudflare 托管模型与 Hugging Face 模型常见示例枚举常量模型标识LLAMA2_7B_FULLcf/meta/llama-2-7b-chat-fp16MISTRAL_7B_INSTRUCTcf/mistral/mistral-7b-instruct-v0.1LLAMA_3_8B_INSTRUCTcf/meta/llama-3-8b-instructGEMMA_7B_IThf/google/gemma-7b-itDEEPSEEK_CODER_6_7_BASEhf/thebloke/deepseek-coder-6.7b-base-awqQWEN1_5_7B_CHAT_AWQcf/qwen/qwen1.5-7b-chat-awq枚举的toString()直接返回模型标识字符串因此可直接作为modelName传入。若 Cloudflare 上架了新模型而枚举尚未更新也可以直接传字符串形式的模型 ID。运行集成测试模块自带针对真实 Cloudflare 账号的集成测试IT运行前需在环境中配置两个变量export WORKERS_AI_ACCOUNT_ID你的账号ID export WORKERS_AI_API_KEY你的API令牌测试类通过EnabledIfEnvironmentVariable注解见 WorkersAiChatModelIT.java判断凭证是否就绪未配置时自动跳过。随后可执行./mvnw -pl langchain4j-workers-ai test源码结构速览模型入口WorkersAiChatModel.java、WorkersAiLanguageModel.java公共抽象与校验AbstractWorkersAIModel.java底层 HTTP 客户端WorkersAiClient.java请求/响应 DTOlangchain4j-workers-ai/src/main/java/dev/langchain4j/model/workersai/client/下的WorkersAiChatCompletionRequest、WorkersAiChatCompletionResponse等测试示例WorkersAiChatModelIT.java、WorkersAiLanguageModelIT.java。注意事项与最佳实践凭证安全切勿将apiToken硬编码在代码或提交到版本库推荐通过环境变量或密钥管理服务注入如上文测试示例所示能力边界本模块不支持流式输出、Tool Calling 与结构化输出需要这些能力时应选择其他提供商集成或自行扩展超时配置默认 30 秒超时适合常规文本任务若使用较大的模型或网络波动明显可通过自定义HttpClientBuilder或WorkersAiClient的timeout调整统一接口的好处由于WorkersAiChatModel/WorkersAiLanguageModel实现了 LangChain4j 标准接口你可以基于ChatModel/LanguageModel抽象编程日后在不同云厂商模型间切换时几乎无需改动业务代码。【免费下载链接】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），仅供参考