Effect AI SDK 是面向 TypeScript 函数式编程范式的 AI 集成方案，通过 @effect/ai-openrouter 包原生支持 OpenRouter。核心模式：用 OpenRouterLanguageModel.model() 声明使用的模型，用 LanguageModel.streamText() 定义交互逻辑，用 OpenRouterClient.layerConfig() 注入 API key 作为 Effect Layer——整个流程类型安全，错误处理由 Effect 框架统一管理。

Effect AI SDK 提供了在 TypeScript Effect 应用中集成 AI 模型的函数式编程接口，通过 @effect/ai-openrouter 包原生支持 OpenRouter。

安装

npm install effect @effect/ai @effect/ai-openrouter @effect/platform

包	作用
effect	Effect 核心运行时
@effect/ai	AI SDK 核心抽象（LanguageModel 等）
@effect/ai-openrouter	OpenRouter 专属 Provider
@effect/platform	HTTP 客户端等平台抽象

完整示例

import { LanguageModel } from "@effect/ai"
import { OpenRouterClient, OpenRouterLanguageModel } from "@effect/ai-openrouter"
import { FetchHttpClient } from "@effect/platform"
import { Config, Effect, Layer, Stream } from "effect"

// 声明使用的模型
const Gpt4o = OpenRouterLanguageModel.model("openai/gpt-4o")

// 定义交互逻辑（尚未执行，只是声明）
const program = LanguageModel.streamText({
  prompt: [
    { role: "system", content: "You are a comedian with a penchant for groan-inducing puns" },
    { role: "user", content: [{ type: "text", text: "Tell me a dad joke" }] }
  ]
}).pipe(
  Stream.filter((part) => part.type === "text-delta"),
  Stream.runForEach((part) => Effect.sync(() => process.stdout.write(part.delta))),
  Effect.provide(Gpt4o)  // 绑定到具体模型
)

// 配置 OpenRouter 客户端（从环境变量读取 API key）
const OpenRouter = OpenRouterClient.layerConfig({
  apiKey: Config.redacted("OPENROUTER_API_KEY")
}).pipe(Layer.provide(FetchHttpClient.layer))

// 执行
program.pipe(
  Effect.provide(OpenRouter),
  Effect.runPromise
)

架构说明

Effect AI SDK 采用依赖注入模式：

1. OpenRouterLanguageModel.model() — 声明模型选择，不含 API key
2. LanguageModel.streamText() — 声明交互逻辑，与 Provider 解耦
3. OpenRouterClient.layerConfig() — 提供 API key 作为 Layer
4. Effect.provide() — 在执行时组合 Layer 和 Program

这种分离使得测试时可以轻松替换 Provider，生产代码无需修改。

更多文档

• Effect AI SDK 文档
• LanguageModel 模块
• OpenRouter 模型列表

常见问题

Q: Effect AI SDK 和直接使用 OpenAI SDK 有什么区别？

A: Effect AI SDK 将 AI 调用纳入 Effect 的类型安全错误处理体系。所有可能失败的操作都有明确的错误类型，不会有未处理的 Promise rejection。如果你的应用已经在用 Effect，这是最自然的集成方式；如果不用 Effect，直接用 OpenAI SDK 更简单。

Q: 如何切换到其他 OpenRouter 模型？

A: 只需修改 OpenRouterLanguageModel.model() 的参数，传入任意 OpenRouter 支持的模型 ID，例如 "anthropic/claude-sonnet-4.6"。

Q: Config.redacted() 和直接用字符串有什么区别？

A: Config.redacted() 从环境变量读取值，并在日志和错误信息中自动遮蔽敏感内容，防止 API key 泄露到输出中。