#模型提供方

模型提供方（provider）是把内核接到真实模型 API 的 ModelProvider 策略。@lite-agent/provider 提供两个受维护适配器——面向 Anthropic Messages API 的 anthropic() 和面向 OpenAI Chat Completions 的 openai()——由于整个 Chat Completions 协议族共享同一套 wire 格式，同一适配器也能驱动 OpenAI 兼容端点和本地端点（Ollama、vLLM、LM Studio、llama.cpp）。两个适配器都把 provider 的 SSE 流翻译成规范化的 ModelChunk，并把所有失败映射为 ProviderError，因此 retry() 等中间件可以跨厂商统一工作。

pnpm add @lite-agent/provider

#快速开始

把 provider 交给 @lite-agent/sdk 的 query（或 core 的 createAgent）：

import { anthropic } from "@lite-agent/provider";
import { query } from "@lite-agent/sdk";

// Reads ANTHROPIC_API_KEY and BASE_URL from env by default.
const claude = anthropic();

for await (const ev of query({ prompt: "Hello!", model: claude, modelName: "claude-sonnet-4-6" })) {
  if (ev.type === "text_delta") process.stdout.write(ev.text);
}

import { openai } from "@lite-agent/provider";

// OpenAI or any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, ...).
// Reads OPENAI_API_KEY and OPENAI_BASE_URL from env by default.
const gpt = openai({ baseURL: "http://localhost:11434/v1" });

#anthropic(options?)

创建一个 ModelProvider（id: "anthropic"），把规范化请求映射到 Anthropic Messages API，内部封装 @anthropic-ai/sdk。

#选项 —— AnthropicProviderOptions

返回的 provider 还会声明 context 能力：自动 prompt 缓存、countTokens，以及——当 client 存在 beta.messages.create 接口时——Anthropic 原生的上下文编辑（clearToolUses、clearThinking、compact）。

import Anthropic from "@anthropic-ai/sdk";
import { anthropic } from "@lite-agent/provider";

const client = new Anthropic({ defaultHeaders: { "x-trace-id": "..." } });
const claude = anthropic({ client });

#openai(options?)

创建一个 ModelProvider（id: "openai"），把规范化请求映射到 OpenAI Chat Completions，内部封装 openai SDK。由于整个协议族共享同一套 wire 格式，同一适配器也可用于 OpenAI 兼容端点和本地端点。

#选项 —— OpenAIProviderOptions

#OpenAI 兼容与本地端点

openai() 接受任何实现了 Chat Completions 的服务器。把 baseURL 指向服务器的 /v1 根路径即可：

import { openai } from "@lite-agent/provider";

// Ollama — https://ollama.com
const ollama = openai({ baseURL: "http://localhost:11434/v1", apiKey: "ollama" });

// vLLM — `vllm serve <model>`
const vllm = openai({ baseURL: "http://localhost:8000/v1", apiKey: "local" });

// LM Studio — local server tab
const lmStudio = openai({ baseURL: "http://localhost:1234/v1", apiKey: "lm-studio" });

// llama.cpp — `llama-server`
const llamaCpp = openai({ baseURL: "http://localhost:8080/v1", apiKey: "local" });

#流式翻译：SSE → ModelChunk

每个适配器的核心职责，是把提供方的 SSE 事件流翻译成 @lite-agent/core 的规范化 ModelChunk 联合类型：

type ModelChunk =
  | { type: "text_delta"; text: string }
  | { type: "message_done"; message: AssistantMessage; usage: Usage };

翻译器保证的行为：

• 文本增量按源顺序流出；拼接结果等于最终的 text 块。
• 工具调用从提供方原生的参数碎片中累积，输出为规范化的 { type: "tool_call", id, name, input } 块，input 为解析后的 JSON。
• 一次成功的流恰好以一个 message_done 结尾，携带完整的 AssistantMessage 和 Usage（inputTokens / outputTokens）。

值得注意的适配器差异：

• Anthropic 还会在上报时把 cacheReadTokens / cacheCreationTokens 带进 usage，支持 compaction 内容块，未知块类型包装为 { type: "native", provider: "anthropic", data }。工具调用 JSON 解析失败会抛错。
• OpenAI 按 index 组装工具调用，参数 JSON 解析失败时回退为 {}。

#错误处理

两个适配器都会捕获 SDK 错误并重新抛出为 ProviderError（来自 @lite-agent/core），在可用时保留数值型 HTTP 状态码：

import { ProviderError } from "@lite-agent/core";

try {
  for await (const ev of query({ prompt: "Hi", model: anthropic(), modelName: "claude-sonnet-4-6" })) { /* ... */ }
} catch (e) {
  if (e instanceof ProviderError) {
    console.error(e.message, e.status); // e.g. 401, 429, 500 — or undefined for non-HTTP failures
  }
}

输出前的失败和流式迭代中途的失败都遵循这一约定，因此 core 的 retry() 中间件可以统一分类处理。

#重试

两个适配器的 maxRetries 都默认 0，这是有意为之：重试策略由 core 的 retry() 中间件统一掌管，SDK 层的重试会与之叠加放大。只有当你确实想让 SDK 自行重试时，才显式设置 maxRetries。

#离线测试：注入 client

两个工厂都接受一个只需满足小型结构化类型的 client——AnthropicClientLike（messages.create 返回原始流事件的异步可迭代对象）或 OpenAIClientLike（chat.completions.create 返回 chunk 流）。这让测试完全确定性、零网络：

import { openai } from "@lite-agent/provider";
import type { OpenAIClientLike } from "@lite-agent/provider";

async function* fakeChunks() {
  yield { choices: [{ delta: { content: "Hello" } }] };
  yield { choices: [{ delta: { content: ", world" } }], usage: { prompt_tokens: 3, completion_tokens: 2 } };
}

const client: OpenAIClientLike = {
  chat: { completions: { create: async () => fakeChunks() } },
};

const provider = openai({ client });
const chunks = [];
for await (const c of provider.stream({ model: "fake", messages: [] })) chunks.push(c);
// chunks: [{ type: "text_delta", text: "Hello" }, { type: "text_delta", text: ", world" }, { type: "message_done", ... }]

本仓库自身的一致性测试套件（conformance suite）也是通过这条缝对两个适配器离线运行的。

#兼容性等级

仓库区分三个支持等级——“OpenAI 兼容”是协议层面的声明，不等于认证：

#探测端点

一个可选的冒烟测试可按需验证真实的 OpenAI 兼容端点（默认 CI 中绝不运行）：

LITE_AGENT_COMPAT_BASE_URL=http://localhost:11434/v1 \
LITE_AGENT_COMPAT_MODEL=qwen3 \
pnpm --filter @lite-agent/provider test:compat

基础 profile 会检查：至少一个文本增量、恰好一个最终 message_done、增量拼接与最终文本一致、usage 字段形态。通过的含义是该端点/运行时/模型组合已验证——不代表该运行时上的每个模型行为一致。

#API 一览

#另请参阅

• 九种策略——这些适配器实现的 ModelProvider 策略接口。
• 工具调用 codec——与这些 provider 搭配 nativeCodec()，或与本地模型搭配 prompt codec。
• 严格单机装配——本地运行时（Ollama、vLLM、LM Studio、llama.cpp）的受维护预设。
• 测试工具——用于零网络测试的 providerConformance 和 fakeProvider。