深入解析effect/ai-openai-compat面向任意 OpenAI 兼容 API 的 Effect AI 适配层与演进全解【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeeffect/ai-openai-compat是 Effect 生态中把 Effect AI 模块LanguageModel、EmbeddingModel桥接到任何 OpenAI 兼容 APIChat Completions 与 Embeddings的适配包。本文以该包完整的 CHANGELOG从4.0.0-beta.0到4.0.0-rc.112为脉络结合仓库内源码实现.repos/effect-smol/packages/ai/openai-compat系统梳理其模块架构、流式协议兼容策略、错误映射模型、工具调用与 Embedding 支持以及版本演进中每一项关键修复背后的实现原理帮助你理解并安全地将其用于自己的 AI 应用。一、包定位与模块总览根据包的 README.md 和 package.json该包的全称为effect/ai-openai-compat当前版本为4.0.0-rc.112官方描述为 An OpenAI compat integration for Effect安装方式为npm install effectrc effect/ai-openai-compatrc与官方effect/ai-openai不同openai-compat面向的是兼容 OpenAI 协议的三方服务——本地推理网关、Azure OpenAI、Fireworks、各类代理与中转服务等。它的src目录见 index.ts对外暴露六个模块模块职责OpenAiClient底层 HTTP 客户端服务chat completions同步/流式与 embeddings 请求的封装、鉴权与错误映射OpenAiConfig作用域化的客户端配置HTTP client transformOpenAiLanguageModel把 OpenAI 兼容 provider 适配为 Effect AI 的LanguageModel服务OpenAiEmbeddingModelEmbedding 模型适配4.0.0-beta.34 起引入OpenAiError附加在共享AiError上的 OpenAI 专有错误元数据OpenAiTelemetry请求/响应的 GenAI 语义化注解telemetry整体调用链可以概括为Effect AI 高层 APILanguageModel.make→OpenAiLanguageModel翻译 Prompt/Tools/Schema →OpenAiClient发出 HTTP 请求 →internal/errors.ts将传输层与状态码错误统一映射为AiError。二、OpenAiClient客户端如何构建与鉴权OpenAiClientOpenAiClient.ts的Options定义了客户端全部可配置项export type Options { readonly apiKey?: Redacted.Redactedstring | undefined readonly apiUrl?: string | undefined readonly organizationId?: Redacted.Redactedstring | undefined readonly projectId?: Redacted.Redactedstring | undefined readonly transformClient?: ((client: HttpClient.HttpClient) HttpClient.HttpClient) | undefined }关键点默认端点apiUrl缺省时为https://api.openai.com/v1make内部通过HttpClientRequest.prependUrl前缀拼接鉴权apiKey以Redacted脱敏容器传入映射为Authorization: Bearer key组织/项目头organizationId、projectId分别写入openai-organization、openai-project请求头且这两个头被注册进Headers.CurrentRedactedNames保证在错误信息与日志中不会被泄露对应 CHANGELOG beta.102 的 Redact OpenAI organization and project headers from client errors 修复请求头统一accept: application/json。make暴露三个方法createResponse——非流式 chat completionsPOST /chat/completions响应体用ChatCompletionResponseSchema 解码返回[body, response]createResponseStream——流式 chat completions自动附加stream: true与stream_options: { include_usage: true }经Sse.decode()解析 SSE 事件遇[DONE]终止createEmbedding——POST /embeddings支持float/base64两种编码格式。layer与layerConfig两种 Layer 构造方式分别对应值已就绪与从Config加载两种场景layerConfig只读取你显式传入的配置项缺省字段以undefined传给make。三、OpenAiConfig作用域化客户端定制OpenAiConfigOpenAiConfig.ts是一个 Context 服务其Service仅包含一个可选字段transformClient。它解决的是不重建客户端层在单个 Effect 作用域内临时定制 HTTP 行为的需求例如添加自定义头、重试、埋点或代理路由export const withClientTransform: { (transform: (client: HttpClient) HttpClient): A, E, R(self: Effect.EffectA, E, R) Effect.EffectA, E, R // ... }从make的实现看存在两层 transformOptions.transformClient在客户端构建时应用而作用域内的OpenAiConfig.withClientTransform在每次请求辅助函数执行时应用且后者的优先级更高——这一点在源码注释中明确标注为 Gotchas是排查为什么我的 transform 没生效时的关键线索。四、流式协议健壮性CHANGELOG 中的核心修复主线回顾 CHANGELOGopenai-compat的多数修复都围绕流式 chat completions 的协议兼容性展开这正是不兼容 provider 最常出问题的地方。下面按时间顺序还原这条主线。4.0.0-rc.110容忍tool_calls: nullPreserve streamed text from OpenAI-compatible providers that sendtool_calls: nullon text-only chunks.PR #7269tim-smart在 OpenAiClient.ts 的ChatCompletionDeltaSchema 中有直接对应的注释与实现// Some OpenAI-compatible providers send tool_calls: null when a streamed // chunk contains only text. Accepting null keeps the text-bearing chunk from // being classified as an unknown event. tool_calls: Schema.optionalKey(Schema.NullOr(Schema.Array(ChatCompletionToolCallDelta)))许多兼容服务在纯文本分片上会把tool_calls显式置为null。此前该字段被声明为可选数组非空导致这些文本分片校验失败、被当作未知事件丢弃用户会看到流式输出缺失文本。把 Schema 改为Schema.NullOr(...)后文本分片得以保留。4.0.0-beta.79修复分片工具调用的参数丢失Fix dropped streamed tool-call arguments when a provider sendsfunction.name: nullon continuation fragments.PR #2338boozedogCHANGELOG 明确给出了真实案例Fireworks这类 provider 只在首个流式tool_calls分片携带工具名后续携带参数增量argument delta的分片会发送function.name: null。此前ChatCompletionToolFunctionDelta.name是Schema.optionalKey(Schema.String)非空续片因此校验失败、参数增量被静默丢弃最终组装出的工具调用参数为空或不完整。修复方式是让name可空Schema.NullOr(Schema.String)。4.0.0-beta.30跨分片保留工具调用 id 与名称Preserve streamed OpenAI compat tool call ids and names across fragmented chat completion chunks.PR #1692与上一条同源流式场景下id、name只出现在首个分片后续分片只带arguments增量。该修复确保在跨分片组装工具调用时id与name不被后续分片覆盖或丢失。4.0.0-beta.103未知流事件可见化与 SSE 状态边界该版本包含三项与流式解码相关的重要变更UnknownChatCompletionEventPR #6667解析出的 chat completion 流事件若与预期 Schema 不匹配不再静默吞掉而是以UnknownChatCompletionEvent类型暴露给上层。源码中可见其定义OpenAiClient.ts且ChatCompletionStreamEvent ChatCompletionChunk | UnknownChatCompletionEvent | [DONE]OpenAiLanguageModel中也有isUnknownChatCompletionEvent判断逻辑SSE 解码器状态上限PR #6777为 pending 的 SSE 解码状态设置可配置的最大事件大小防止恶意或异常的大事件撑爆内存工具调用参数统一解码PR #6882流式与非流式的工具调用参数arguments统一使用 provider 面向的 OpenAI Schema codec 解码避免两种路径行为不一致。4.0.0-beta.103连续工具调用合并Group consecutive tool calls into one assistant message when using Chat Completions APIs.PR #6719IMax153使用 Chat Completions 协议时若模型在一条回复中连续发起多个工具调用此前可能被拆成多条 assistant 消息该修复将其归并为一条消息、携带多个tool_calls更贴近 OpenAI 协议语义也能规避部分 provider 对消息序列的严格校验。五、错误处理从 HTTP 状态码到结构化AiErrorOpenAiClient对错误的统一出口是AiError映射逻辑集中在 internal/errors.ts。状态码映射规则mapStatusCodeToReasonHTTP 状态AiError类型kind / 备注400InvalidRequestError请求体非法401AuthenticationErrorkind: InvalidKey403AuthenticationErrorkind: InsufficientPermissions404 / 409 / 422InvalidRequestError资源缺失 / 冲突 / 无法处理429QuotaExhaustedError或RateLimitError依据errorCode/errorType是否含insufficient_quota、quota、exhausted判定配额耗尽其他InternalProviderError/UnknownError等无法归类的错误4.0.0-rc.112认证错误携带 provider 原始文本Add an optionaldescriptiontoAiError.AuthenticationError, rendered after the kind-based suggestion, and pass the providers own error text through it on HTTP 401 and 403PR #7437wmaurer此前 401/403 只给出类别化的提示如 InvalidKey、InsufficientPermissions用户无法得知具体原因。现在AuthenticationError新增可选description并将 provider 返回的原始错误文本透传——例如invalid api key、你的账户已欠费这类信息会原样呈现。对应的OpenAiErrorMetadataOpenAiError.ts统一携带errorCode、errorType、requestId三个字段并通过 TS module augmentation 挂到AiError各类的metadata.openai上。速率限制头解析parseRateLimitHeaders从响应头中解析retry-after、x-ratelimit-limit-requests、x-ratelimit-remaining-requests、x-ratelimit-reset-requests、x-ratelimit-reset-tokens其中retry-after会被转换为Duration供上层实现退避重试。OpenAiRateLimitMetadata在AiError.RateLimitErrorMetadata上以openai键暴露这些字段。安全细节buildHttpRequestDetails与buildHttpContext在构造错误上下文时统一使用Redactable.redact处理请求/响应头确保 token、密钥不落入错误对象错误体解析OpenAiErrorBody使用 Schema 解码并兼容错误体是数组的异常情况取数组首项。六、OpenAiLanguageModelPrompt 与 Schema 的适配机制OpenAiLanguageModelOpenAiLanguageModel.ts是高层适配器通过三种构造器暴露model(model, config?)——返回携带 provider/model 元数据的AiModel.Modelopenai, ...描述符可用Effect.provide注入make({ model, config })——构造LanguageModel.Service同时支持generateText与streamTextlayer({ model, config })——以Layer形式装配。配置合并优先级为{ model, ...providerConfig, ...Context 中的 Config }即上下文中的Config服务优先级最高withConfigOverride则为单个 effect 提供作用域覆盖同样遵循覆盖值优先。关键适配逻辑system/developer 消息切换getSystemMessageMode当模型名以o、gpt-5、codex-、computer-use开头时system 消息改用developerrole这对应新一代 OpenAI 模型对developer角色的支持文件与图片image/*媒体被映射为input_image支持file_id、image_url、data:...;base64,三种形式PDF 映射为input_file其他媒体类型返回InvalidRequestErrorfileIdPrefixes配置决定字符串数据是文件 ID还是base64 内容OpenAI 通常为file-Azure OpenAI 为assistant-结构化输出通过codecTransformer: toCodecOpenAI将 Effect Schema codec 转换为 OpenAI 兼容的 JSON Schema 请求格式strictJsonSchema默认true控制是否启用严格模式reasoning 与 item 引用支持store: true时以item_reference引用历史 item、跳过重复项避免 Duplicate item found 错误支持reasoning.encrypted_content的回传见include枚举与ReasoningItem处理verbositytext.verbosity默认为medium映射到请求的text.verbosity字段。4.0.0-beta.63内部配置字段泄漏修复FixOpenAiLanguageModelleaking library-only config fields (fileIdPrefixes,strictJsonSchema) into request body, causing OpenAI 400 errors.PR #2133Zelys-DFKHfileIdPrefixes与strictJsonSchema只是库内部控制字段不属于 OpenAI 协议参数。此前它们会被混入请求体导致 provider 返回 400。修复后在构造请求时通过解构剔除const { fileIdPrefixes: _fip, strictJsonSchema: _sjs, ...apiConfig } config这提醒我们接入兼容服务时请求体必须严格贴合协议字段任何库内部字段外泄都可能触发 provider 的严格校验。4.0.0-beta.98空消息内容归一化与配置自动补全空 assistant 内容归一化PR #2576部分 OpenAI 兼容 provider 拒绝content: null现将空 assistant 消息内容归一化为空字符串配置自动补全PR #2608保留已知 OpenAI 兼容模型配置属性的自动补全同时允许 provider 自定义属性对应ModelConfig中的readonly [x: string]: unknown索引签名与OpenAiLanguageModel/Config服务的同类扩展点。4.0.0-beta.28 / beta.27自定义请求属性与 reasoning 透传beta.28PR #1634允许在模型配置与 chat request 类型中使用自定义请求属性并将模型级自定义属性转发到 chat-completions payload——这是接入私有 provider 扩展字段如reasoning_effort类参数的通道beta.27PR #1623将OpenAiLanguageModel的reasoning配置转发进 chat-completions 请求。七、Embedding 与工具调用的能力演进4.0.0-beta.34PR #1764新增不稳定的EmbeddingModel支持——core 侧增加 EmbeddingModel 服务/请求/响应类型、RequestResolver批量batching、embed/embedManyspans、确定性排序与空输入快速路径effect/ai-openai-compat侧增加 OpenAI 兼容的 EmbeddingModel provider 支持配置覆盖、layer 构造器、输出索引校验与确定性重排。beta.34还要求 embedding provider 的model构造器必须显式声明ModelDimensionsPR #17714.0.0-beta.42PR #1859为 openai 与 openai-compat 语言模型加入动态工具dynamic tooling能力4.0.0-beta.20PR #1528新增Model.ModelName并由 AI 模型构造器提供方便上层追踪实际使用的模型名。八、Telemetry语义化注解与命名空间修正OpenAiTelemetry模块提供addGenAIAnnotations为请求与响应附加 GenAI 语义注解。CHANGELOG 中 beta.106 连续两项修复都与它有关PR #7126修正 OpenAI 响应 telemetry 属性的类型改为使用发出的响应命名空间emitted response namespacePR #7127修正 OpenAI 兼容 telemetry 的响应属性命名空间。二者都属于属性挂载位置/类型与生态约定不一致的修正升级到 beta.106 后 telemetry 数据才能被标准 GenAI 观测面板正确归类。九、API 整洁度与版本迁移提示移除显式入口点beta.103PR #6701删除显式./indexentrypoints统一以effect/ai-openai-compat的包级导出为准package.json 中./index: null、./*/index: null明确禁用了这些入口允许undefined的 ai configbeta.15PR #1502Config相关字段允许undefined降低配置组合时的类型摩擦AiErrormetadata 接口按 reason 拆分beta.20PR #1529为每个 error reason 定义专属 metadata 接口避免 provider 包通过declare module扩展时产生冲突——第三方 provider 扩展 metadata 时应遵循这一模式4.0.0-beta.0PR #1183v4 beta 主版本起点之后所有版本均为 4.0.0 的 RC/预发布序列API 仍在演进中生产使用请锁定精确版本并关注Updated dependencies: effect...的对应关系。十、实践建议小结结合 CHANGELOG 与源码接入effect/ai-openai-compat时有几点值得注意流式兼容问题优先看 Schema文本丢失、工具调用参数为空等玄学问题多半是 provider 在tool_calls、function.name、content等字段上返回了null而非省略。rc.110 与 beta.79 的修复方式Schema.NullOr、空字符串归一化是排查这类问题的最佳参照错误诊断看metadata.openaierrorCode、errorType、requestId三件套加上 rc.112 引入的description足以定位 401/403/429/400 的具体原因结合parseRateLimitHeaders解析出的retry-after可做退避重试请求体只放协议字段fileIdPrefixes、strictJsonSchema这类库内部字段不要混入 payloadbeta.63 的教训自定义 provider 特性走config索引签名与withConfigOverridebeta.28 的自定义属性透传为私有字段留了后门而作用域覆盖withConfigOverride、withClientTransform可避免为不同环境重建 Layer。若需查看各版本对应effect核心库的依赖变更可直接对照 CHANGELOG.md 中每版本的 Updated dependencies 段它们与effect4.0.0-rc.*/4.0.0-beta.*一一对应。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
深入解析 `@effect/ai-openai-compat`：面向任意 OpenAI 兼容 API 的 Effect AI 适配层与演进全解
深入解析effect/ai-openai-compat面向任意 OpenAI 兼容 API 的 Effect AI 适配层与演进全解【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeeffect/ai-openai-compat是 Effect 生态中把 Effect AI 模块LanguageModel、EmbeddingModel桥接到任何 OpenAI 兼容 APIChat Completions 与 Embeddings的适配包。本文以该包完整的 CHANGELOG从4.0.0-beta.0到4.0.0-rc.112为脉络结合仓库内源码实现.repos/effect-smol/packages/ai/openai-compat系统梳理其模块架构、流式协议兼容策略、错误映射模型、工具调用与 Embedding 支持以及版本演进中每一项关键修复背后的实现原理帮助你理解并安全地将其用于自己的 AI 应用。一、包定位与模块总览根据包的 README.md 和 package.json该包的全称为effect/ai-openai-compat当前版本为4.0.0-rc.112官方描述为 An OpenAI compat integration for Effect安装方式为npm install effectrc effect/ai-openai-compatrc与官方effect/ai-openai不同openai-compat面向的是兼容 OpenAI 协议的三方服务——本地推理网关、Azure OpenAI、Fireworks、各类代理与中转服务等。它的src目录见 index.ts对外暴露六个模块模块职责OpenAiClient底层 HTTP 客户端服务chat completions同步/流式与 embeddings 请求的封装、鉴权与错误映射OpenAiConfig作用域化的客户端配置HTTP client transformOpenAiLanguageModel把 OpenAI 兼容 provider 适配为 Effect AI 的LanguageModel服务OpenAiEmbeddingModelEmbedding 模型适配4.0.0-beta.34 起引入OpenAiError附加在共享AiError上的 OpenAI 专有错误元数据OpenAiTelemetry请求/响应的 GenAI 语义化注解telemetry整体调用链可以概括为Effect AI 高层 APILanguageModel.make→OpenAiLanguageModel翻译 Prompt/Tools/Schema →OpenAiClient发出 HTTP 请求 →internal/errors.ts将传输层与状态码错误统一映射为AiError。二、OpenAiClient客户端如何构建与鉴权OpenAiClientOpenAiClient.ts的Options定义了客户端全部可配置项export type Options { readonly apiKey?: Redacted.Redactedstring | undefined readonly apiUrl?: string | undefined readonly organizationId?: Redacted.Redactedstring | undefined readonly projectId?: Redacted.Redactedstring | undefined readonly transformClient?: ((client: HttpClient.HttpClient) HttpClient.HttpClient) | undefined }关键点默认端点apiUrl缺省时为https://api.openai.com/v1make内部通过HttpClientRequest.prependUrl前缀拼接鉴权apiKey以Redacted脱敏容器传入映射为Authorization: Bearer key组织/项目头organizationId、projectId分别写入openai-organization、openai-project请求头且这两个头被注册进Headers.CurrentRedactedNames保证在错误信息与日志中不会被泄露对应 CHANGELOG beta.102 的 Redact OpenAI organization and project headers from client errors 修复请求头统一accept: application/json。make暴露三个方法createResponse——非流式 chat completionsPOST /chat/completions响应体用ChatCompletionResponseSchema 解码返回[body, response]createResponseStream——流式 chat completions自动附加stream: true与stream_options: { include_usage: true }经Sse.decode()解析 SSE 事件遇[DONE]终止createEmbedding——POST /embeddings支持float/base64两种编码格式。layer与layerConfig两种 Layer 构造方式分别对应值已就绪与从Config加载两种场景layerConfig只读取你显式传入的配置项缺省字段以undefined传给make。三、OpenAiConfig作用域化客户端定制OpenAiConfigOpenAiConfig.ts是一个 Context 服务其Service仅包含一个可选字段transformClient。它解决的是不重建客户端层在单个 Effect 作用域内临时定制 HTTP 行为的需求例如添加自定义头、重试、埋点或代理路由export const withClientTransform: { (transform: (client: HttpClient) HttpClient): A, E, R(self: Effect.EffectA, E, R) Effect.EffectA, E, R // ... }从make的实现看存在两层 transformOptions.transformClient在客户端构建时应用而作用域内的OpenAiConfig.withClientTransform在每次请求辅助函数执行时应用且后者的优先级更高——这一点在源码注释中明确标注为 Gotchas是排查为什么我的 transform 没生效时的关键线索。四、流式协议健壮性CHANGELOG 中的核心修复主线回顾 CHANGELOGopenai-compat的多数修复都围绕流式 chat completions 的协议兼容性展开这正是不兼容 provider 最常出问题的地方。下面按时间顺序还原这条主线。4.0.0-rc.110容忍tool_calls: nullPreserve streamed text from OpenAI-compatible providers that sendtool_calls: nullon text-only chunks.PR #7269tim-smart在 OpenAiClient.ts 的ChatCompletionDeltaSchema 中有直接对应的注释与实现// Some OpenAI-compatible providers send tool_calls: null when a streamed // chunk contains only text. Accepting null keeps the text-bearing chunk from // being classified as an unknown event. tool_calls: Schema.optionalKey(Schema.NullOr(Schema.Array(ChatCompletionToolCallDelta)))许多兼容服务在纯文本分片上会把tool_calls显式置为null。此前该字段被声明为可选数组非空导致这些文本分片校验失败、被当作未知事件丢弃用户会看到流式输出缺失文本。把 Schema 改为Schema.NullOr(...)后文本分片得以保留。4.0.0-beta.79修复分片工具调用的参数丢失Fix dropped streamed tool-call arguments when a provider sendsfunction.name: nullon continuation fragments.PR #2338boozedogCHANGELOG 明确给出了真实案例Fireworks这类 provider 只在首个流式tool_calls分片携带工具名后续携带参数增量argument delta的分片会发送function.name: null。此前ChatCompletionToolFunctionDelta.name是Schema.optionalKey(Schema.String)非空续片因此校验失败、参数增量被静默丢弃最终组装出的工具调用参数为空或不完整。修复方式是让name可空Schema.NullOr(Schema.String)。4.0.0-beta.30跨分片保留工具调用 id 与名称Preserve streamed OpenAI compat tool call ids and names across fragmented chat completion chunks.PR #1692与上一条同源流式场景下id、name只出现在首个分片后续分片只带arguments增量。该修复确保在跨分片组装工具调用时id与name不被后续分片覆盖或丢失。4.0.0-beta.103未知流事件可见化与 SSE 状态边界该版本包含三项与流式解码相关的重要变更UnknownChatCompletionEventPR #6667解析出的 chat completion 流事件若与预期 Schema 不匹配不再静默吞掉而是以UnknownChatCompletionEvent类型暴露给上层。源码中可见其定义OpenAiClient.ts且ChatCompletionStreamEvent ChatCompletionChunk | UnknownChatCompletionEvent | [DONE]OpenAiLanguageModel中也有isUnknownChatCompletionEvent判断逻辑SSE 解码器状态上限PR #6777为 pending 的 SSE 解码状态设置可配置的最大事件大小防止恶意或异常的大事件撑爆内存工具调用参数统一解码PR #6882流式与非流式的工具调用参数arguments统一使用 provider 面向的 OpenAI Schema codec 解码避免两种路径行为不一致。4.0.0-beta.103连续工具调用合并Group consecutive tool calls into one assistant message when using Chat Completions APIs.PR #6719IMax153使用 Chat Completions 协议时若模型在一条回复中连续发起多个工具调用此前可能被拆成多条 assistant 消息该修复将其归并为一条消息、携带多个tool_calls更贴近 OpenAI 协议语义也能规避部分 provider 对消息序列的严格校验。五、错误处理从 HTTP 状态码到结构化AiErrorOpenAiClient对错误的统一出口是AiError映射逻辑集中在 internal/errors.ts。状态码映射规则mapStatusCodeToReasonHTTP 状态AiError类型kind / 备注400InvalidRequestError请求体非法401AuthenticationErrorkind: InvalidKey403AuthenticationErrorkind: InsufficientPermissions404 / 409 / 422InvalidRequestError资源缺失 / 冲突 / 无法处理429QuotaExhaustedError或RateLimitError依据errorCode/errorType是否含insufficient_quota、quota、exhausted判定配额耗尽其他InternalProviderError/UnknownError等无法归类的错误4.0.0-rc.112认证错误携带 provider 原始文本Add an optionaldescriptiontoAiError.AuthenticationError, rendered after the kind-based suggestion, and pass the providers own error text through it on HTTP 401 and 403PR #7437wmaurer此前 401/403 只给出类别化的提示如 InvalidKey、InsufficientPermissions用户无法得知具体原因。现在AuthenticationError新增可选description并将 provider 返回的原始错误文本透传——例如invalid api key、你的账户已欠费这类信息会原样呈现。对应的OpenAiErrorMetadataOpenAiError.ts统一携带errorCode、errorType、requestId三个字段并通过 TS module augmentation 挂到AiError各类的metadata.openai上。速率限制头解析parseRateLimitHeaders从响应头中解析retry-after、x-ratelimit-limit-requests、x-ratelimit-remaining-requests、x-ratelimit-reset-requests、x-ratelimit-reset-tokens其中retry-after会被转换为Duration供上层实现退避重试。OpenAiRateLimitMetadata在AiError.RateLimitErrorMetadata上以openai键暴露这些字段。安全细节buildHttpRequestDetails与buildHttpContext在构造错误上下文时统一使用Redactable.redact处理请求/响应头确保 token、密钥不落入错误对象错误体解析OpenAiErrorBody使用 Schema 解码并兼容错误体是数组的异常情况取数组首项。六、OpenAiLanguageModelPrompt 与 Schema 的适配机制OpenAiLanguageModelOpenAiLanguageModel.ts是高层适配器通过三种构造器暴露model(model, config?)——返回携带 provider/model 元数据的AiModel.Modelopenai, ...描述符可用Effect.provide注入make({ model, config })——构造LanguageModel.Service同时支持generateText与streamTextlayer({ model, config })——以Layer形式装配。配置合并优先级为{ model, ...providerConfig, ...Context 中的 Config }即上下文中的Config服务优先级最高withConfigOverride则为单个 effect 提供作用域覆盖同样遵循覆盖值优先。关键适配逻辑system/developer 消息切换getSystemMessageMode当模型名以o、gpt-5、codex-、computer-use开头时system 消息改用developerrole这对应新一代 OpenAI 模型对developer角色的支持文件与图片image/*媒体被映射为input_image支持file_id、image_url、data:...;base64,三种形式PDF 映射为input_file其他媒体类型返回InvalidRequestErrorfileIdPrefixes配置决定字符串数据是文件 ID还是base64 内容OpenAI 通常为file-Azure OpenAI 为assistant-结构化输出通过codecTransformer: toCodecOpenAI将 Effect Schema codec 转换为 OpenAI 兼容的 JSON Schema 请求格式strictJsonSchema默认true控制是否启用严格模式reasoning 与 item 引用支持store: true时以item_reference引用历史 item、跳过重复项避免 Duplicate item found 错误支持reasoning.encrypted_content的回传见include枚举与ReasoningItem处理verbositytext.verbosity默认为medium映射到请求的text.verbosity字段。4.0.0-beta.63内部配置字段泄漏修复FixOpenAiLanguageModelleaking library-only config fields (fileIdPrefixes,strictJsonSchema) into request body, causing OpenAI 400 errors.PR #2133Zelys-DFKHfileIdPrefixes与strictJsonSchema只是库内部控制字段不属于 OpenAI 协议参数。此前它们会被混入请求体导致 provider 返回 400。修复后在构造请求时通过解构剔除const { fileIdPrefixes: _fip, strictJsonSchema: _sjs, ...apiConfig } config这提醒我们接入兼容服务时请求体必须严格贴合协议字段任何库内部字段外泄都可能触发 provider 的严格校验。4.0.0-beta.98空消息内容归一化与配置自动补全空 assistant 内容归一化PR #2576部分 OpenAI 兼容 provider 拒绝content: null现将空 assistant 消息内容归一化为空字符串配置自动补全PR #2608保留已知 OpenAI 兼容模型配置属性的自动补全同时允许 provider 自定义属性对应ModelConfig中的readonly [x: string]: unknown索引签名与OpenAiLanguageModel/Config服务的同类扩展点。4.0.0-beta.28 / beta.27自定义请求属性与 reasoning 透传beta.28PR #1634允许在模型配置与 chat request 类型中使用自定义请求属性并将模型级自定义属性转发到 chat-completions payload——这是接入私有 provider 扩展字段如reasoning_effort类参数的通道beta.27PR #1623将OpenAiLanguageModel的reasoning配置转发进 chat-completions 请求。七、Embedding 与工具调用的能力演进4.0.0-beta.34PR #1764新增不稳定的EmbeddingModel支持——core 侧增加 EmbeddingModel 服务/请求/响应类型、RequestResolver批量batching、embed/embedManyspans、确定性排序与空输入快速路径effect/ai-openai-compat侧增加 OpenAI 兼容的 EmbeddingModel provider 支持配置覆盖、layer 构造器、输出索引校验与确定性重排。beta.34还要求 embedding provider 的model构造器必须显式声明ModelDimensionsPR #17714.0.0-beta.42PR #1859为 openai 与 openai-compat 语言模型加入动态工具dynamic tooling能力4.0.0-beta.20PR #1528新增Model.ModelName并由 AI 模型构造器提供方便上层追踪实际使用的模型名。八、Telemetry语义化注解与命名空间修正OpenAiTelemetry模块提供addGenAIAnnotations为请求与响应附加 GenAI 语义注解。CHANGELOG 中 beta.106 连续两项修复都与它有关PR #7126修正 OpenAI 响应 telemetry 属性的类型改为使用发出的响应命名空间emitted response namespacePR #7127修正 OpenAI 兼容 telemetry 的响应属性命名空间。二者都属于属性挂载位置/类型与生态约定不一致的修正升级到 beta.106 后 telemetry 数据才能被标准 GenAI 观测面板正确归类。九、API 整洁度与版本迁移提示移除显式入口点beta.103PR #6701删除显式./indexentrypoints统一以effect/ai-openai-compat的包级导出为准package.json 中./index: null、./*/index: null明确禁用了这些入口允许undefined的 ai configbeta.15PR #1502Config相关字段允许undefined降低配置组合时的类型摩擦AiErrormetadata 接口按 reason 拆分beta.20PR #1529为每个 error reason 定义专属 metadata 接口避免 provider 包通过declare module扩展时产生冲突——第三方 provider 扩展 metadata 时应遵循这一模式4.0.0-beta.0PR #1183v4 beta 主版本起点之后所有版本均为 4.0.0 的 RC/预发布序列API 仍在演进中生产使用请锁定精确版本并关注Updated dependencies: effect...的对应关系。十、实践建议小结结合 CHANGELOG 与源码接入effect/ai-openai-compat时有几点值得注意流式兼容问题优先看 Schema文本丢失、工具调用参数为空等玄学问题多半是 provider 在tool_calls、function.name、content等字段上返回了null而非省略。rc.110 与 beta.79 的修复方式Schema.NullOr、空字符串归一化是排查这类问题的最佳参照错误诊断看metadata.openaierrorCode、errorType、requestId三件套加上 rc.112 引入的description足以定位 401/403/429/400 的具体原因结合parseRateLimitHeaders解析出的retry-after可做退避重试请求体只放协议字段fileIdPrefixes、strictJsonSchema这类库内部字段不要混入 payloadbeta.63 的教训自定义 provider 特性走config索引签名与withConfigOverridebeta.28 的自定义属性透传为私有字段留了后门而作用域覆盖withConfigOverride、withClientTransform可避免为不同环境重建 Layer。若需查看各版本对应effect核心库的依赖变更可直接对照 CHANGELOG.md 中每版本的 Updated dependencies 段它们与effect4.0.0-rc.*/4.0.0-beta.*一一对应。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考