使用 AI SDK 接入 GMI CloudOpenAI 兼容协议下的开源权重模型推理实战【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiGMI Cloud 是一个提供 GPU 推理服务的云平台面向开源权重open-weight模型提供托管式 API其接口遵循 OpenAI 兼容协议。本文基于 AI SDK 仓库中的ai-sdk/gmicloudprovider 包源码位于 packages/gmicloud完整讲解它的安装、Provider 实例化、语言模型调用方式与错误诊断机制。读完本文你将掌握如何在 AI SDK 应用中用寥寥几行代码接入 GMI Cloud 的推理服务、如何自定义 API 配置baseURL、headers、fetch 等并理解该 provider 如何解析 GMI Cloud 特有的嵌套错误结构从而在排障时快速定位后端引擎的真实报错原因。背景GMI Cloud 与 AI SDK 的定位GMI Cloud 为开源权重模型提供 GPU 推理服务通过 OpenAI 兼容的 chat completions 接口对外提供模型能力。AI SDK 是面向 TypeScript 的 AI 应用构建工具集ai-sdk/gmicloud是其中的一个 provider 包它把 GMI Cloud 的 HTTP 接口适配成 AI SDK 的 LanguageModelV4 抽象使开发者可以用统一的方式调用generateText、streamText等 AI SDK 核心 API而不必关心底层协议细节。从 packages/gmicloud/package.json 可以看到该包的设计要点依赖ai-sdk/openai-compatible、ai-sdk/provider、ai-sdk/provider-utils其中ai-sdk/openai-compatible是承载 OpenAI 兼容协议实现的底层模块说明 GMI Cloud 的接入复用了通用的 OpenAI 兼容适配层声明engines.node 22使用 ESM 模块格式构建产物为dist/index.js通过prepack脚本将仓库内的 100-gmicloud.mdx 文档一并打包发布。安装与基础配置安装 provider 包GMI Cloud provider 发布在ai-sdk/gmicloud模块中使用 npm 即可安装npm i ai-sdk/gmicloud安装时注意它与aiAI SDK 核心包配合使用例如在 examples/ai-e2e-next 等示例应用中模型 provider 与核心ai包是成对出现的。如果你的项目还没有安装 AI SDK 核心包需要一并安装ai。默认 Provider 实例该包导出一个默认的 provider 实例gmicloud可以直接导入使用import { gmicloud } from ai-sdk/gmicloud;默认实例直接由createGmicloud()无参创建见 gmicloud-provider.ts因此它采用全部默认配置默认读取环境变量GMI_CLOUD_APIKEY作为 API Key默认请求地址为https://api.gmi-serving.com/v1。也就是说只要在环境中设置了GMI_CLOUD_APIKEY导入gmicloud即可开始调用模型无需任何额外配置。API Key 可以在 GMI Cloud 控制台获取。自定义 Provider 实例createGmicloud当需要自定义配置时使用createGmicloud创建实例。例如显式传入 API Keyimport { createGmicloud } from ai-sdk/gmicloud; const gmicloud createGmicloud({ apiKey: process.env.GMI_CLOUD_APIKEY ?? , });createGmicloud接收一个GmicloudProviderSettings配置对象其完整字段与语义如下与 gmicloud-provider.ts 中的类型定义一一对应配置项类型默认值说明apiKeystring环境变量GMI_CLOUD_APIKEY通过Authorization: Bearer apiKey请求头发送baseURLstringhttps://api.gmi-serving.com/v1API 调用的 URL 前缀可指向代理或兼容端点headersRecordstring, string无附加到每次请求的自定义请求头fetchFetchFunction全局fetch自定义 fetch 实现可用于拦截请求或注入测试环境从源码实现可以看到几个值得注意的细节URL 拼接provider 会用withoutTrailingSlash去掉baseURL末尾多余的斜杠再与路径拼接gmicloud-provider.ts。例如默认配置下chat completions 请求最终指向https://api.gmi-serving.com/v1/chat/completions这一点在 gmicloud-provider.test.ts 的测试用例中有直接断言。User-Agent 后缀每次请求都会附加ai-sdk/gmicloud/版本号的 User-Agent 后缀gmicloud-provider.ts方便服务端识别 SDK 调用方。版本号来自构建期注入的VERSION常量见 version.ts。API Key 加载通过loadApiKey读取优先级是「显式传入的apiKey 环境变量GMI_CLOUD_APIKEY」未找到时会抛出带说明的错误。请求头合并Authorization头在合并顺序上位于自定义headers之前因此自定义 headers 可以覆盖默认的鉴权头等字段。语言模型调用基础调用示例GMI Cloud provider 的核心用法与 AI SDK 其他 provider 一致把gmicloud(modelId)作为model传入 AI SDK 的生成函数。以下是最简单的文本生成示例import { gmicloud } from ai-sdk/gmicloud; import { generateText } from ai; const { text } await generateText({ model: gmicloud(deepseek-ai/DeepSeek-V4-Flash-0731), prompt: What is the capital of France?, });generateText返回结果中的text即模型的完整回复。由于gmicloud实例实现了 AI SDK 的ProviderV4接口gmicloud(modelId)、gmicloud.chat(modelId)与gmicloud.languageModel(modelId)三种写法等价见 gmicloud-provider.ts可以按项目风格任选其一。此外该实例还支持 AI SDK 工作流Workflow的序列化/反序列化能力见 gmicloud-chat-language-model.ts。模型 ID 列表与动态目录GMI Cloud 提供的是持续演进的模型目录因此该 provider 将模型 ID 的类型定义为string而不是固定的字符串字面量联合类型。源码中 gmicloud-chat-options.ts 列出了一些已知模型 ID 作为参考deepseek-ai/DeepSeek-V4-Flash-0731Qwen/Qwen3.8-Maxmoonshotai/kimi-k3zai-org/GLM-5.2-FP8MiniMaxAI/MiniMax-M3这些 ID 仅作示例实际可用的完整模型列表可通过GET https://api.gmi-serving.com/v1/models获取该 URL 在源码注释中有标注。由于类型是string即使目录更新增加了新模型你也不需要升级 provider 包就能直接传入新 ID。能力边界不支持 Embedding 与图像模型GMI Cloud provider 只提供语言模型chat completions能力。从 gmicloud-provider.ts 可以看到embeddingModel与imageModel方法会直接抛出NoSuchModelErrortextEmbeddingModel被标记为deprecated并同样抛出该错误。对应的测试 gmicloud-provider.test.ts 也验证了这一行为。因此如果你的场景需要 embedding 或图像生成应选择其他 provider如仓库 packages 目录下的其他厂商包而不是 GMI Cloud。文本对话、文本生成、流式输出、函数调用等语言模型能力则可以正常使用。错误诊断解包嵌套的引擎错误GMI Cloud 的「双层错误」结构这是 GMI Cloud provider 最有特色的部分。当请求被拒绝时GMI Cloud 的边缘网关edge会返回一个「外层横幅」错误error.message只有笼统的Backend request failed with status 400真正的后端引擎诊断信息被嵌套在error.details字段里details是一个 JSON 字符串内部还有一个带message的error对象。如果直接用默认的 OpenAI 兼容错误处理details里的信息会被丢弃开发者只能看到毫无排查价值的通用横幅。GMI Cloud provider 专门实现了自定义的错误结构来解包这层嵌套。核心实现在 gmicloud-error.ts用 zod 定义了gmicloudErrorDataSchema描述外层错误结构message、type、param、code、details等字段unwrapDetailsMessage函数尝试对details做安全的 JSON 解析secureJsonParse取出内部error.messageerrorToMessage的优先级是内部诊断信息优先外层横幅兜底——只要details能解析出非空字符串的message就用它否则回退到外层error.message。export const gmicloudErrorStructure: ProviderErrorStructureGmicloudErrorData { errorSchema: gmicloudErrorDataSchema, errorToMessage: data unwrapDetailsMessage(data.error.details) ?? data.error.message, };这个gmicloudErrorStructure在创建语言模型时被注入gmicloud-provider.ts底层实现是GmicloudChatLanguageModel继承自OpenAICompatibleChatLanguageModel唯一的定制点就是错误结构见 gmicloud-chat-language-model.ts 的注释说明。效果AI_APICallError.message 携带真实原因解包之后抛出的AI_APICallError.message将携带后端引擎的真实诊断。例如 README 中给出的实际场景The request is invalid: Invalid max_tokens value, the valid range of max_tokens is [1, 393216].而不是无用的Backend request failed with status 400。这让开发者能直接看到问题根因——比如 max_tokens 超出范围、thinking 模式下不支持某种 tool_choice、请求体中出现了模型不认识的字段如 image_url等。测试用例佐证gmicloud-error.test.ts 使用从api.gmi-serving.com/v1/chat/completions逐字抓取的响应体作为测试夹具覆盖了多种真实场景max_tokens 越界解包出Invalid max_tokens value, the valid range of max_tokens is [1, 393216]thinking 模式与 tool_choice 冲突解包出Thinking mode does not support this tool_choice非法输入类型解包出messages[0]: unknown variant image_url, expected text印证图像输入不受支持兜底回退当details缺失、不是合法 JSON、或内部没有message时回退到外层横幅纯文本 404 响应GMI 的边缘对不存在的模型会返回纯文本如No matching target server found for model foo此时 zod schema 校验失败provider 会转而依赖 HTTP 状态文本而不是误解析。这些用例同时验证了解包逻辑的健壮性与「内部优先、外层兜底」的设计意图。在 AI SDK 应用中的使用建议结合以上机制在实际项目中使用 GMI Cloud provider 时有几点建议密钥管理优先通过环境变量GMI_CLOUD_APIKEY注入密钥避免把 API Key 硬编码进源码多环境部署时可使用createGmicloud({ apiKey })覆盖。自定义端点如果通过企业网关、代理或兼容网关访问用baseURL指向你的端点URL 前缀末尾是否带斜杠不影响拼接结果。错误处理捕获AI_APICallError时直接读取.message它通常已经是可读的后端诊断如果诊断信息仍不充分可以结合error.details原始字段进一步分析。模型选择模型 ID 通过GET https://api.gmi-serving.com/v1/models查询最新目录由于 ID 类型是宽松的string新增模型无需升级 SDK。能力边界embedding 与图像模型调用会抛出NoSuchModelError架构设计时应提前为这两类能力选用其他 provider。以上配置与调用方式均基于当前仓库中 packages/gmicloud 的实际源码与测试实现可直接对照 gmicloud-provider.ts、gmicloud-error.ts 与对应测试文件进行验证。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考