---
id: AI-API-001
category: Unified
confidence_score: 1.0
tags: [software-engineering, api-design, ai-services, streaming, grpc, rest]
last_reinforced: 2026-04-26
---

# API Design for AI Services (AI 서비스를 위한 API 디자인)

## 📌 한 줄 통찰 (The Karpathy Summary)
> "긴 추론 시간과 거대한 데이터 흐름을 우아하게 추상화하라" — 모델의 비결정적 출력과 비동기적 연산 특성을 고려하여 개발자가 예측 가능하고 효율적으로 AI 기능을 통합할 수 있도록 설계된 인터페이스.

## 📖 구조화된 지식 (Synthesized Content)
- **추출된 패턴:** 동기식 요청-응답의 한계를 넘어 스트리밍, 비동기 작업 큐, 상태 보존형 세션 등을 통해 고사양 연산 자원을 효율적으로 노출하는 서비스 인터페이스 패턴.
- **핵심 설계 원칙:**
    - **Streaming First:** LLM의 토큰 생성을 실시간으로 전달하기 위해 SSE(Server-Sent [[Events|Events]])나 WebSockets 필수 적용.
    - **[[State|State]]less vs Stateful:** 대화 맥락 유지(Conversation ID)와 모델 가중치 독립성을 위한 상태 관리 전략.
    - **Asynchronous Execution:** 시간이 오래 걸리는 태스크(이미지 생성 등)를 위한 Job ID 기반의 폴링(Polling) 또는 웹훅(Webhook) 구조.
    - **Safety & Filtering:** API 수준에서 유해 결과물을 차단하는 가드레일 레이어 통합.
    - **Version Control:** 모델 버전 업데이트 시 결과물의 미세한 변화를 고려한 시맨틱 버저닝.

## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- **과거 데이터와의 충돌:** 정적인 데이터를 주고받던 REST API에서, 실시간 추론과 대규모 멀티모달 데이터를 처리하는 동적인 인터페이스로 설계 중심이 이동.
- **정책 변화:** Antigravity 프로젝트는 모든 에이전트 간 통신에 gRPC 스트리밍을 우선 사용하며, 외부 웹 인터페이스 제공 시에는 SSE 표준을 준수하여 사용자 경험을 최적화함.

## 🔗 지식 연결 (Graph)
-[[_system|system]]-Design-for-AI-Scale, [[LLM|LLM]], Streaming-Data-[[Processing|Processing]], Microservices
- **Raw Source:** 10_Wiki/Topics/AI/API-Design for AI Services.md