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、多模態模型、向量儲存或代理協定通訊的應用程式都能實現低成本、快速且決定性的測試。