CopilotKit/aimock

aimock – 用于 AI 应用测试的确定性模拟服务器

是什么 – aimock（原名 llmock）是一个单包、零依赖的 Node.js 服务器，可模拟您的应用可能调用的所有主要 LLM、视觉、语音、视频、嵌入、向量数据库和代理间端点。通过将 SDK 指向其提供的本地端口，您即可获得完全确定性的响应，无需任何真实 API 密钥或网络流量，从而消除意外计费，并使端到端测试更加可靠。

为何重要 – 真实的 AI 服务成本高昂、有速率限制，且可能随时间变化。aimock 让开发者只需记录一次真实交互，即可永久回放，同时支持混沌测试、漂移检测和细粒度的用例路由。这使得 CI 流水线快速、廉价且可复现。

---

核心组件（“aimock 套件”）

组件	模拟内容	典型使用场景
LLMock	OpenAI（聊天、实时、图像、音频、视频）、Claude、Gemini、Bedrock、Azure、Vertex AI、Ollama、Cohere、OpenRouter、ElevenLabs TTS、BytePlus Ark、Grok 等	在单元/集成测试中替换任何 LLM 或多模态提供商。
MCPMock	Copilot-Kit MCP 工具、资源、提示词并支持会话处理	在无需实时服务器的情况下测试提示管理后端。
A2AMock	代理间 SSE 流式协议	验证多代理协调逻辑。
AGUIMock	AG-UI 事件流（代理→UI）	面向 UI 驱动代理的前端测试。
VectorMock	Pinecone、Qdrant、ChromaDB 兼容的向量存储 API	测试检索增强生成流水线。
Services	Tavily 搜索、Cohere 重排序、OpenAI 审核、ElevenLabs TTS	模拟许多代理依赖的辅助服务。

所有这些组件均可在一个端口上运行（npx @copilotkit/aimock --config aimock.json），或通过程序化方式启动，以实现更紧密的测试框架集成。

---

主要功能

• 录制 & 回放 – 代理真实 API，存储精确的 JSON 负载（包括每帧时间戳），然后永久回放。回放速度可通过 --replay-speed 调整。
• 时间感知回放 – 保留首令牌延迟（ttft）和整体令牌/秒节奏，有助于测试 UI 加载状态。
• 准确的令牌使用量与成本 – 记录的使用帧被回放，使计费相关代码能识别真实的 prompt_tokens、completion_tokens 和提供商特定的成本分解。
• 多轮对话支持 – 用例可限定于特定轮次、工具调用、系统消息或自定义谓词，支持真实工具使用场景。
• 混沌测试 – 支持随机 500 错误、格式错误的 JSON、中途断开连接，以及可配置的速率限制头，用于验证重试/退避逻辑。
• 严格 vs. 宽松匹配 – 全局 --strict 标志或每请求 X-AIMock-Strict 头控制未匹配请求是否报错。
• 基于上下文的用例路由 – X-AIMock-Context 头可为每个集成隔离用例集，避免跨测试污染。
• 漂移检测 – CI 作业可自动将记录的用例与实时 API 对比，以捕捉提供商变更。
• 流式物理模拟 – 可调整 ttft、每秒令牌数和抖动，以模拟真实的流式行为。
• 指标 – Prometheus 兼容端点（/metrics）报告请求次数、延迟和用例命中率。
• Docker 与 Helm – 提供官方容器镜像和 Helm 图表，便于在 CI/CD 流水线中部署。
• 测试框架插件 – Vitest 和 Jest 辅助函数（useAimock()）可自动启动/停止服务器并修补环境变量。

---

典型工作流程

1. 安装 – npm i @copilotkit/aimock。
2. 录制（可选） – 在您的应用与真实提供商通信时运行 npx @copilotkit/aimock llmock --record --provider-openai https://api.openai.com。用例将保存为 JSON 文件。
3. 回放 – 使用这些用例启动模拟服务器：npx @copilotkit/aimock --config aimock.json（或通过 new LLMock({port:0}) 程序化启动）。
4. 指向 SDK – 将 OPENAI_BASE_URL（其他提供商同理）设置为 http://localhost:<port>/v1，并提供任意假 API 密钥。
5. 运行测试 – 您的测试套件现在将命中模拟服务器，接收确定性响应，并可通过头或 CLI 标志测试错误/延迟场景。

---

安装与快速入门（来自 README 的代码片段）

npm install @copilotkit/aimock

import { LLMock } from "@copilotkit/aimock";

const mock = new LLMock({ port: 0 });
mock.onMessage("hello", { content: "Hi there!" });
await mock.start();

process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
process.env.OPENAI_API_KEY = "mock"; // 多数 SDK 所需

// … 运行您的应用/测试 …
await mock.stop();

---

集成点

• LangChain、CrewAI、LlamaIndex、Mastra、Google ADK、Microsoft Agent Framework – 专用指南展示了如何将提供商 URL 替换为 aimock。
• GitHub Action – CopilotKit/aimock@v1 可预加载用例，并将模拟 URL 暴露给后续步骤。
• CLI 工具 – llmock（兼容别名）用于标志驱动运行，aimock convert 用于从其他模拟工具导入用例，Docker 命令用于容器化 CI。

---

谁在使用？

AG-UI 项目在其端到端测试套件中引用 aimock，以使用用例驱动响应验证跨多个 LLM 提供商的代理行为。

---

许可证

MIT – 免费用于商业和开源用途。

---

总结 – aimock 是一个全面的、零依赖的模拟服务器，覆盖了现代生成式 AI 服务的完整栈。它使任何与 LLM、多模态模型、向量存储或代理协议通信的应用程序都能实现低成本、快速且确定性的测试。