---
id: aitrain-provider-abstraction
title: "AITRAIN 프로바이더 추상화"
category: "AI_Training"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["AI training provider", "어댑터 학습 추출", "외부 API 통합 원리"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.89
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["ai-training", "provider", "adapter", "transferable", "astraai"]
raw_sources: ["AstraAI/src/features/providers/index.ts", "AstraAI/src/features/providers/anthropic.ts", "AstraAI/src/features/providers/types.ts"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[AITRAIN 프로바이더 추상화]]

## 🎯 한 줄 통찰 (One-line insight)
외부 API 통합의 전이 원리는 "차이는 가장자리(어댑터)에서 흡수하고 중심은 단일 포맷으로 정규화하며, 라우팅은 명시적 키로" 이다 — 구현은 [[LLM 프로바이더 추상화]], 결정 근거는 [[ADR-0008 로컬우선 LLM 클라우드 폴백]].

## 📖 세부 내용 (Details · 8-field 추출)
- **Concept:** 다수의 이질적 외부 서비스를 호출부 입장에선 하나처럼 보이게 하는 어댑터 계층.
- **Implementation:** model id prefix 라우팅(parseModelPrefix), 공급자별 streamX 어댑터, 응답을 공통 OpenAI-SSE 로 변환, 에러는 passthrough, 활성 공급자만 병렬 조회.
- **Design Reasoning:** 같은 모델명이 여러 경로에 존재 → 출처 명시 필요; 호출부를 공급자 무관하게 유지하려 정규화; 프라이버시·비용 위해 로컬 우선.
- **Tradeoffs:** 호출부 단순·교체 용이 ↔ 어댑터별 구현·정규화 비용·키 관리.
- **Failure Modes:** 인증 실패, 응답 형식 차이, 모델 목록 노후화, role 교대/system 위치 같은 공급자 제약.
- **Debugging Strategy:** 에러 Response.text(), 어댑터별 입력 정규화 점검, prefix 매칭 확인.
- **Improvement Ideas:** prompt caching/tool use, 자동 모델 목록, 난이도 기반 라우팅.
- **Reusable Principles:** ① *차이는 가장자리에서* 흡수, 중심은 단일 모델. ② 라우팅은 *명시 키(prefix)* 로 모호성 제거. ③ 입력/출력을 *정규화* 해 상위 코드를 공급자 무관하게. ④ 외부 실패는 삼키지 말고 *그대로 전달*해 호출부가 안내. ⑤ 기본은 *프라이버시·비용 안전*, 품질은 옵션.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[AstraAI 아키텍처 개요]]
- **관련 개념:** [[API Client Pattern]], [[Tool Calling Pattern]], [[프로젝트 독립 설계 원칙]]
- **참조 맥락:** 작은 모델이 다중 외부 API/SDK 통합을 다른 프로젝트에서 설계할 때 전이.

## 📚 출처 (Sources)
- [S1] AstraAI/src/features/providers/index.ts, anthropic.ts, types.ts

## 📝 변경 이력 (Change history)
- 2026-06-13: AI 학습용 지식 추출 초안.
