企业官网建设流程全解析

effect-smol AI模块完全指南：提供商无关的LLM接口

【免费下载链接】effect-smolCore libraries and experimental work for Effect v4项目地址: https://gitcode.com/GitHub_Trending/ef/effect-smol

effect-smol 是 Effect v4 核心库的官方仓库，其AI 模块提供了一套提供商无关的 LLM 接口：你只需实现一次业务逻辑，就可以在 OpenAI、Anthropic、OpenRouter 等多家大模型服务之间自由切换。本指南带你快速上手这套接口，包括文本生成、结构化输出、流式响应、工具调用与多会话管理。

一、为什么选择 effect-smol 的 AI 模块

传统 LLM SDK 往往绑定单一提供商，更换供应商意味着重写大量代码。effect-smol 的 AI 模块采用统一抽象设计，带来三大好处：

核心接口定义在 packages/effect/src/unstable/ai/ 目录，包含 LanguageModel.ts、Chat.ts、Tool.ts 等关键模块。

二、4 个官方提供商包一览

仓库在 packages/ai/ 下提供了四个开箱即用的提供商适配包：

• @effect/ai-openai—— 官方 OpenAI 客户端与模型，源码见 OpenAiLanguageModel.ts
• @effect/ai-anthropic—— Claude 系列模型适配，源码见 AnthropicLanguageModel.ts
• @effect/ai-openai-compat—— 兼容任意 OpenAI 风格 API 的自托管模型
• @effect/ai-openrouter—— 通过 OpenRouter 一站式接入多家模型，源码见 OpenRouterLanguageModel.ts

配置模式完全一致：用Config从环境变量读取 API Key，再叠加一个HttpClient即可，例如OpenAiClient.layerConfig与AnthropicClient.layerConfig。

三、LanguageModel 的 3 种输出模式

LanguageModel是整套接口的核心，提供三种生成方式（完整示例见 ai-docs/src/71_ai/10_language-model.ts）：

1️⃣ 纯文本生成：generateText

传入 prompt 即可获取回复，响应自带finishReason、usage（token 用量）等便捷字段，无需手动解析。

2️⃣ 结构化对象：generateObject

传入一个Schema，模型输出会被自动校验并解码为类型安全的对象。比如把一段会议笔记直接转成带受众、渠道、日期、风险的 LaunchPlan 对象，省去脆弱的 JSON 解析代码。

3️⃣ 流式响应：streamText

返回Stream，可逐段接收text-delta部分，非常适合打字机效果的聊天界面。

四、ExecutionPlan：多提供商自动降级 ⭐

这是最实用的特性之一。用ExecutionPlan.make可以定义"先试便宜模型、失败再切昂贵模型"的降级策略：

const DraftPlan = ExecutionPlan.make( { provide: OpenAiLanguageModel.model("gpt-5.2"), attempts: 3 }, { provide: AnthropicLanguageModel.model("claude-opus-4-6"), attempts: 2 } )

上面表示：先用 OpenAI 模型尝试 3 次，失败后自动回退到 Anthropic 模型。业务代码通过Effect.withExecutionPlan(draftsModel)应用该策略，一行代码获得跨供应商容灾能力。

五、Tools 与 Toolkit：让模型调用你的函数

AI 模块内置了类型安全的工具调用体系（示例见 ai-docs/src/71_ai/20_tools.ts）：

1. 定义工具：Tool.make指定名称、描述、参数 Schema 和成功结果 Schema
2. 组成工具箱：Toolkit.make把多个工具聚合为类型化工具箱
3. 实现处理器：toLayer返回一个Layer，为每个工具提供 Effect 形式的处理器
4. 传给模型：调用generateText时传入toolkit，框架自动完成参数解析、调用处理器、回填结果的闭环

还支持toolChoice: "required"强制模型先调用工具，以及提供商内置工具（如 OpenAI 的 WebSearch）与自定义工具混用。

六、Chat 模块：有状态的多轮对话

Chat.ts 提供自动维护会话历史的对话能力（示例见 ai-docs/src/71_ai/30_chat.ts）：

• Chat.fromPrompt创建会话，可附带 system 提示词
• 每一轮session.generateText都会自动累积上下文，无需手动管理消息数组
• exportJson/fromJson支持会话序列化与恢复
• 每轮可注入不同模型，实现对话中途切换供应商
• 配合Toolkit即可构建代理循环（Agent Loop）：模型调用工具 → 框架回填结果 → 直到模型给出最终答案

七、错误处理与可观测性

• 统一的 AiError.ts 错误类型，含AiErrorReason，可用Schema.TaggedErrorClass映射为你的业务错误
• 各提供商包内置遥测模块（如 OpenAiTelemetry.ts），便于接入 OpenTelemetry 追踪

八、快速上手路径 🚀

只需记住一句话：配置提供商一次，用统一的LanguageModel接口写业务，切换模型和供应商只是换一层 Layer 的事—— 这正是 effect-smol AI 模块"提供商无关"设计的核心价值。

【免费下载链接】effect-smolCore libraries and experimental work for Effect v4项目地址: https://gitcode.com/GitHub_Trending/ef/effect-smol