Anthropic 不会喜欢这个开源仓库。它将让大语言模型服务商付出高昂代价。如今，AI 应用的每一次 CI 运行都会向 OpenAI 或 Anthropic 等服务商发送真实请求。与任何其他 LLM 调用一样，这也会按实际 API 费率计费。因此，对于提交量大的团队，API 开支会累积成可观的费用。开发者常用的一个技巧是调用本地模拟服务器代替真实 LLM API，该服务器响应相同 API 格式并返回虚拟响应。但问题在于虚拟响应只是保存之日服务商返回数据的副本，而服务商会持续新增字段和修改类型。因此测试会通过一个已失效的 schema，而真正的集成测试却在生产环境中失败。现在，@CopilotKit 最近开源的 aimock 项目实现了更智能的方案：该仓库自身的 CI 每天向真实 API 发送少量请求，同时向模拟服务器发送相同请求，然后根据官方客户端库的类型定义对比两者结果。这是整个设置中唯一的真实 API 调用，且运行在仓库自己的密钥上，而非其他人的 CI 中。单个团队每天可能推送数百次提交，而当前已有数千个团队通过编程代理执行此操作。所有这些运行都保持离线状态，因为一个仓库代表所有人检查真实 API。当检查失败时，编程代理会更新 aimock 内置的响应 schema，全套测试必须通过，然后将补丁版本发布到 npm。只需升级包，修正后的 schema 就会反映在所有使用它的项目中。该功能不限于单一服务商——同一服务器适用于 Claude、OpenAI、Gemini、Bedrock、Azure、Ollama，以及 MCP 工具、A2A 代理、AG-UI 事件流、Pinecone 和 Qdrant 等向量数据库，还有搜索、语音、图像和视频端点。仓库地址：https://github.com/CopilotKit/aimock…（别忘了点星！）当然，模拟 API 调用只是一方面。AI 工程师还应了解如何正确测试代理，而许多团队仍跳过这一步。我撰写了一篇完整指南，涵盖构建、测试、评估、追踪和部署。请阅读下文。

CopilotKit/aimock

来源：https://github.com/CopilotKit/aimock

aimock

AI 应用测试的模拟基础设施 —— 将你的 SDK 指向一个本地端口，所有服务商、协议和服务都会确定性地响应。 快速开始 · 工具套件 · 录制与重放 (https://aimock.copilotkit.dev/record-replay) · 文档 (https://aimock.copilotkit.dev/docs) npm (https://www.npmjs.com/package/@copilotkit/aimock) 单元测试 (https://github.com/CopilotKit/aimock/actions/workflows/test-unit.yml) 漂移测试 (https://github.com/CopilotKit/aimock/actions/workflows/test-drift.yml) 许可证：MIT https://github.com/user-attachments/assets/76815122-574a-48e1-b275-edae0a014667 一个包，一个端口，零依赖。LLM API、图像生成与编辑、文本转语音、转写、音频翻译与生成、视频生成、嵌入向量、MCP 工具、A2A 代理、AG-UI 事件流、向量数据库、搜索、重排序和内容审核 —— 无需密钥、无需网络、无意外账单。

快速开始

npm install @copilotkit/aimock

// 类名仍保留为 `LLMock` 以兼容 v1.7.0 后从 `@copilotkit/llmock` 更名至 `@copilotkit/aimock` 的包。
import { LLMock } from "@copilotkit/aimock";
const mock = new LLMock({ port: 0 });
mock.onMessage("hello", { content: "Hi there!" });
await mock.start();

// 在导入/构建 OpenAI（或其他服务商）客户端之前设置环境变量。
// 许多 SDK 在构建时会缓存 base URL —— 如果在设置前构建客户端，
// 它将连接真实 API（产生意外账单）而非 aimock。
process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
process.env.OPENAI_API_KEY = "mock"; // SDK 需要值，即使 base URL 被模拟
// ... 运行你的测试 ...
await mock.stop();

aimock 工具套件

aimock 模拟你的 AI 应用连接的所有服务：

使用 npx @copilotkit/aimock --config aimock.json 在一个端口运行所有工具，或使用编程 API 组合你需要的精确功能。

功能特性

• 录制与重放 (https://aimock.copilotkit.dev/record-replay) —— 代理真实 API，保存为固件，永久确定性重放
• 感知时间的录制与重放 —— 录制的固件捕获每帧到达时间戳；重放使用记录的时间线，基于记录的 TTFT（首令牌时间）和帧间间隔进行近似时间重现（重放块数可能与录制不同——保留 TTFT 和平均节奏，而非逐令牌保真度），可配置 --replay-speed 倍率
• 多轮对话 (https://aimock.copilotkit.dev/multi-turn) —— 录制和重放带工具调用的多轮追踪；通过 turnIndex、hasToolResult、toolCallId、toolResultContains（基于工具结果负载匹配）、sequenceIndex、systemMessage（基于宿主提供的代理上下文匹配）或自定义谓词区分不同轮次
• 15 个 API 接口覆盖 13 家服务商 (https://aimock.copilotkit.dev/docs) —— OpenAI Chat、OpenAI Responses、OpenAI Realtime (GA + Beta 模拟)、Claude、Gemini REST、Gemini embedContent、Gemini Live、Gemini Interactions、Azure、Bedrock、Vertex AI、Ollama (chat + embeddings)、Cohere (chat + embed)、OpenRouter (chat + 路由器故障转移)、ElevenLabs TTS —— 完整流式支持
• 多媒体 API —— 图像生成 (https://aimock.copilotkit.dev/images) (DALL-E, Imagen)、图像编辑 (https://aimock.copilotkit.dev/images) (/v1/images/edits)、文本转语音 (https://aimock.copilotkit.dev/speech) (OpenAI + ElevenLabs)、音频转写 (https://aimock.copilotkit.dev/transcription)、音频翻译 (https://aimock.copilotkit.dev/transcription) (/v1/audio/translations)、视频生成 (https://aimock.copilotkit.dev/video)、OpenRouter 视频生成 (https://aimock.copilotkit.dev/openrouter-video) (/api/v1/videos 带异步作业生命周期)、Google Veo 视频生成 (https://aimock.copilotkit.dev/veo-video) (:predictLongRunning + /v1beta/operations 异步生命周期)、Grok Imagine 视频生成 (https://aimock.copilotkit.dev/grok-video) (/v1/videos/generations 带异步作业生命周期)、fal.ai (https://aimock.copilotkit.dev/fal-ai) (图像/视频/音频带队列生命周期)
• MCP (https://aimock.copilotkit.dev/mcp-mock) / A2A (https://aimock.copilotkit.dev/a2a-mock) / AG-UI (https://aimock.copilotkit.dev/agui-mock) / 向量 (https://aimock.copilotkit.dev/vector-mock) —— 模拟你的 AI 代理使用的所有协议
• 混沌测试 (https://aimock.copilotkit.dev/chaos-testing) —— 500 错误、畸形 JSON、任意概率的流中中断
• 逐请求严格模式 —— X-AIMock-Strict 请求头可按请求覆盖服务器级的 --strict 标志（true/1 = 严格，false/0 = 宽松）
• 基于上下文的固件路由 —— X-AIMock-Context 请求头可限定固件的作用域；带 match.context 的固件仅匹配携带该上下文的请求，不带该字段的固件保持共享
• 漂移检测 (https://aimock.copilotkit.dev/drift-detection) —— 每日 CI 针对真实 API 的验证
• 流式物理模拟 (https://aimock.copilotkit.dev/streaming-physics) —— 可配置的 ttft（首令牌时间）、tps（令牌/秒）和 jitter（抖动）
• WebSocket API (https://aimock.copilotkit.dev/websocket) —— OpenAI Realtime (GA 协议，模型包括：gpt-realtime、gpt-realtime-2、gpt-realtime-1.5、gpt-realtime-mini；通过 gpt-4o-transcribe、gpt-4o-mini-transcribe、whisper-1 进行转写/翻译；图像输入；解说阶段)、Responses WS、Gemini Live
• Prometheus 指标 (https://aimock.copilotkit.dev/metrics) —— 请求计数、延迟、固件匹配率
• Docker + Helm (https://aimock.copilotkit.dev/docker) —— 用于 CI/CD 的容器镜像和 Helm 图表
• Vitest 与 Jest 插件 (https://aimock.copilotkit.dev/test-plugins) —— 零配置的 useAimock()，自动生命周期和环境补丁
• 响应覆盖 (https://aimock.copilotkit.dev/fixtures) —— 控制固件响应中的 id、model、usage、finishReason
• 有序块 (https://aimock.copilotkit.dev/fixtures#ordered-blocks) —— blocks 数组可按任意顺序流式传输文本和工具调用（工具优先或交错）；仅块的固件是一等公民，录制器会捕获真正工具优先/交错流的顺序
• 流式用量块 (https://aimock.copilotkit.dev/streaming-physics) —— stream_options.include_usage 支持会发出包含令牌计数的最终块，匹配 OpenAI 的流式用量协议
• 速率限制头 (https://aimock.copilotkit.dev/chaos-testing) —— 每个响应包含 x-ratelimit-* 头，429 错误时包含 Retry-After 头，用于测试重试/退避逻辑
• 零依赖 —— 完全基于 Node.js 内置模块

GitHub Action

- uses: CopilotKit/aimock@v1
  with:
    fixtures: ./test/fixtures
- run: npm test
  env:
    OPENAI_BASE_URL: http://127.0.0.1:4010/v1

查看 GitHub Action 文档 (https://aimock.copilotkit.dev/github-action) 获取所有输入参数和示例。

CLI

# 仅 LLM 模拟
npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures

# 远程固件 —— 从 HTTPS URL 加载 JSON（可重复）
npx -p @copilotkit/aimock llmock -p 4010 \
  -f https://raw.githubusercontent.com/acme/mocks/main/openai.json \
  -f ./fixtures/local-overrides.json

# 从配置文件运行完整套件
npx @copilotkit/aimock --config aimock.json

# 录制模式：代理真实 API，保存固件
npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.com

# 为推理模型录制时延长超时
npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.com \
  --body-timeout-ms 180000

# 以 2 倍速度重放录制的固件
npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures --replay-speed 2

# 从其他工具转换固件
npx @copilotkit/aimock convert vidaimock ./templates/ ./fixtures/
npx @copilotkit/aimock convert mockllm ./config.yaml ./fixtures/

# Docker
docker run -d -p 4010:4010 -v "$(pwd)/fixtures:/fixtures" ghcr.io/copilotkit/aimock -f /fixtures -h 0.0.0.0

关于 llmock 与 aimock CLI 的说明。 llmock 可执行文件保留为 @copilotkit/llmock 1.7.0 之前版本的兼容别名。它运行一个功能更窄的基于标志的 CLI，不支持 --config 或 convert 子命令。新项目应使用 aimock（或 npx @copilotkit/aimock）以获得完整功能支持。

远程固件 URL

--fixtures 除文件系统路径外，还接受指向 JSON 固件文件的 https:// 和 http:// URL，且该标志可重复使用，因此您可以在 argv 中按顺序叠加远程和本地源。获取的固件会缓存到磁盘的 ~/.cache/aimock/fixtures//（遵循 $XDG_CACHE_HOME）；与 --validate-on-load 配对时，如果获取失败但存在有效缓存副本，将记录警告并继续——没有缓存时，进程会以非零状态退出。HTTP 获取有 10 秒超时和 50 MB 体大小限制；重定向会失败并明确报错，因此请配置您的上游直接提供最终 URL（GitHub 原始内容 URL 已满足此要求）。默认拒绝私有和链路本地地址（环回、RFC1918、CGNAT、云元数据、ULA、多播）以防止 SSRF。对于需要访问 127.0.0.1 的本地开发或测试，可通过 AIMOCK_ALLOW_PRIVATE_URLS=1 选择退出。Tarball 和 zip URL 支持暂未实现。

重放匹配与 AIMOCK_STRICT_TURN_INDEX

重放时，turnIndex 是一个非致命的消歧器，而非严格拒绝门控：即使固件的 turnIndex 与请求的助手消息计数不同，内容匹配的固件也会被提供。这消除了多轮代理运行中误报的“无固件匹配”（多步代理在每个逻辑轮次会发出多个助手气泡）。当提供的固件与其脚本化的 turnIndex 不符时，匹配诊断会携带 turnIndexRelaxed: true，aimock 会记录一次性警告（在 warn 日志级别——默认静默）。要恢复旧版的严格行为（即定义的 turnIndex 必须精确等于助手计数），请设置 AIMOCK_STRICT_TURN_INDEX=1。录制路径始终严格，不受此标志影响。

API 密钥验证

默认情况下 aimock 接受所有请求。可通过编程选项、顶级 aimock.json 字段或仅环境变量的密钥列表选择性启用入站测试客户端验证：

await createServer(fixtures, {
  auth: { apiKeys: ["test-key"] }
});

{
  "auth": {
    "apiKeys": ["test-key"]
  }
}

AIMOCK_API_KEYS=test-key,rotated-key npx @copilotkit/aimock --config aimock.json

使用 Authorization: Bearer 、Authorization: Key 、x-api-key、x-goog-api-key、api-key 或 xi-api-key。每个提供的凭据必须解析为一个已配置的密钥；不匹配则返回 401 及 OpenAI 兼容的认证错误。HTTP 路由、控制 API、挂载点和 WebSocket 升级受保护。真正的 CORS 预检请求以及 GET /health、GET /ready 和 GET /metrics 保持公开。这是入站测试访问控制，不同于 record.providerKeys；启用后，代理会剥离测试凭据，并在出口前要求配置的静态服务商凭据。

aimock 拥有的上游密钥 —— AIMOCK_PROVIDER_*_KEY

在录制或 --proxy-only 模式下，aimock 将调用者的认证头原样转发给真实服务商。如果你的测试只能发送虚拟占位符密钥（例如某些 SDK 在非空 API 密钥前无法启动），aimock 可以在固件未命中透传时注入其自身配置的上游密钥，以便代理的调用实际完成认证。每个服务商有独立的环境变量，密钥按服务商正确的线路方案应用：

Gemini Interactions API（/v1beta/models/*:generateContent）使用 x-goog-api-key，而 Vertex AI 端点使用 OAuth2 令牌——aimock 的 Vertex AI 支持通过 record.providerKeys 配置静态令牌。