CopilotKit/aimock

aimock – AI 애플리케이션 테스트를 위한 모의 인프라

소개

• 외부 의존성이 없는 Node 전용 라이브러리로, 단일 포트에서 로컬 HTTP 서버를 실행하여 코드에서 호출할 수 있는 모든 주요 LLM, 이미지/비디오/오디오, 벡터 저장소 및 AI 에이전트 서비스를 시뮬레이션합니다.
• 사용하는 SDK(OpenAI, Anthropic, Gemini, Bedrock, Ollama 등)의 기본 URL을 모의 서버로 지정하면 애플리케이션이 결정론적인 응답을 받게 됩니다. 네트워크 호출이나 API 키가 필요 없으며 예상치 못한 비용도 발생하지 않습니다.

중요성

• AI 강화 애플리케이션의 단위 테스트 및 통합 테스트를 안정적이고 빠르게 만듭니다.
• 기록 및 재생(record‑and‑replay) 지원: 실제 API를 한 번 프록시하고 정확한 JSON 픽스처(토큰 사용량, 타이밍, 스트리밍 순서 포함)를 저장한 후 영구적으로 재생할 수 있습니다.
• 다양한 테스트 제어 기능 제공: 혼란 주입, 모델 오작동 시뮬레이션, 엄격 모드 매칭, 요청별 컨텍스트 라우팅 등을 통해 오류 처리, 속도 제한 재시도 및 엣지 케이스 동작을 검증할 수 있습니다.

핵심 구성 요소

구성 요소	모의 대상
LLMock	11개 공급업체(OpenAI, Claude, Gemini, Bedrock, Azure, Vertex, Ollama, Cohere, OpenRouter, BytePlus, ElevenLabs 등)의 채팅, 임베딩, 실시간, 비디오, 이미지, TTS, 전사, 조정
MCPMock	Copilot‑Kit의 MCP 도구 실행 프로토콜
A2AMock	에이전트 간 스트리밍 프로토콜 (SSE)
AGUIMock	프론트엔드 테스트를 위한 에이전트-UI 이벤트 스트림
VectorMock	Pinecone, Qdrant, ChromaDB 호환 벡터 저장소 엔드포인트
Services	검색 (Tavily), 리랭크 (Cohere), 조정 (OpenAI)

주요 기능 (README 설명 기준)

• 기록 및 재생: 타이밍 인식 재생 및 토큰 사용량/비용 캡처 기능.
• 다중 턴 대화: 턴 인덱스, 도구 호출, 시스템 메시지 또는 사용자 정의 조건에 따라 매칭 가능한 픽스처.
• 혼란 테스트: 500 오류, 잘못된 JSON, 연결 끊김, 속도 제한 응답 또는 인위적인 지연 주입.
• 모델 오작동: 여러 공급업체 "와이어" 전반에 걸쳐 잘못된 인수, 스키마 위반, 거부, 콘텐츠 필터 차단 등을 강제.
• 스트리밍 물리: 첫 토큰 시간(TTFT), 초당 토큰 수, 지터 및 스트리밍 사용 청크 설정.
• WebSocket 지원: OpenAI Realtime, Responses 및 Gemini Live 지원.
• 메트릭: Prometheus를 통한 메트릭, CI/CD용 Docker/Helm 이미지, 제로 구성 테스트 수명 주기를 위한 Vitest/Jest 플러그인 (useAimock()).
• 픽스처 관리: 컨텍스트 기반 라우팅, 엄격 모드 재정의, 요청 저널, OpenAPI 카탈로그 및 드리프트 감지 CI 검사.

일반적인 사용법

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();

CLI를 통해 전체 스위트를 실행할 수도 있습니다:

npx @copilotkit/aimock --config aimock.json   # 모든 모의 서버를 하나의 포트에서 실행

또는 GitHub Action을 사용하여 CI에서 서버를 가동하고 테스트를 해당 서버로 지정할 수 있습니다.

사용 권장 대상

• 클라우드 비용 없이 빠르고 반복 가능한 테스트가 필요한 AI 기반 제품 개발자.
• 오류 처리, 속도 제한 백오프 또는 사용자 정의 도구 호출 로직을 검증하려는 팀.
• 실제 API 상호 작용을 한 번 캡처하고 오프라인 개발을 위해 결정론적으로 재생해야 하는 모든 개발자.

---

위의 모든 세부 정보는 저장소의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.