aisuite 딥다이브
— 문자열 하나만 바꾸면 LLM 공급자가 갈리는 "통합 어댑터"의 설계

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

aisuite는 유니폼 액세스 레이어(uniform access layer)를 표방하는 경량 라이브러리다. 두 개의 층으로 나뉜다 — ① 공급자 간 통일된 Chat Completions API, ② 그 위에서 모델에게 파이썬 함수를 도구로 쥐여 주는 Agents API. 여기에 같은 저장소에서 두 층을 실제로 써먹는 데스크탑 앱 OpenCoworker까지 함께 배포된다. 핵심 패키지(aisuite/)는 순수 파이썬이며, 공급자 SDK는 모두 선택적(optional) 의존성이라 필요한 것만 골라 설치한다(pip install 'aisuite[anthropic]').

2왜 주목받는가

트렌딩 이유 · LiteLLM 등 경쟁 대비 장점.

멀티 공급자 통합 라이브러리는 이미 여럿(LiteLLM, LangChain 등) 있다. aisuite가 빠르게 주목받은 이유는 셋이다. 첫째 Andrew Ng이라는 강력한 브랜드와 "최소한의 추상화" 철학, 둘째 OpenAI SDK를 그대로 베낀 친숙한 표면(surface), 셋째 단순 채팅을 넘어 Agents API·MCP·OpenCoworker 앱까지 한 저장소에서 위로 쌓아 올린 점이다.

3기술 스택 전체 지도

코어 라이브러리·공급자 SDK·에이전트/인프라 각각.

① 코어 라이브러리 (백엔드) — 순수 파이썬 추상화

코어는 외부 의존성이 거의 없다. 공급자 SDK들은 전부 optional이라, 코어 자체는 pydantic·httpx·docstring-parser 정도만 필수로 요구한다. 무거운 SDK를 강제하지 않는 것이 "경량(lightweight)"의 핵심.

② 공급자 SDK (선택 설치) — extras로 골라 담기

pyproject.toml의 [tool.poetry.extras]에 공급자별 설치 그룹이 정의돼 있다. pip install 'aisuite[all]'로 전부, 또는 aisuite[anthropic]처럼 하나만 설치한다.

③ 에이전트 · 인프라 · 앱

4아키텍처 심화 분석

model 문자열 → 동적 어댑터 로딩 → 변환/정규화, 그리고 도구 루프.

전체 흐름 한눈에 — 3층 + 어댑터

호출부는 model="provider:model-name" 문자열을 넘긴다. Client는 콜론 앞부분(provider)을 키로 삼아, ProviderFactory가 이름 규칙으로 해당 어댑터 모듈을 런타임에 import하고 인스턴스를 만든다. 그 어댑터가 요청을 그 회사 SDK 형식으로 변환해 호출하고, 응답을 다시 OpenAI 형식으로 정규화해 돌려준다.

핵심 ① 동적 공급자 로딩 — "if-else 분기"가 아니라 "이름 규칙"

aisuite의 가장 우아한 부분이다. 공급자가 20개가 넘는데도, 코드 어디에도 if provider == "openai": ... elif "anthropic": ... 같은 거대한 분기가 없다. 대신 파일 이름과 클래스 이름의 규칙으로 어댑터를 찾아낸다.

class ProviderFactory:
    PROVIDERS_DIR = Path(__file__).parent / "providers"

    @classmethod
    def create_provider(cls, provider_key, config):
        # "anthropic" → 클래스 "AnthropicProvider"
        provider_class_name  = f"{provider_key.capitalize()}Provider"
        # "anthropic" → 모듈 "anthropic_provider"
        provider_module_name = f"{provider_key}_provider"
        module_path = f"aisuite.providers.{provider_module_name}"

        module = importlib.import_module(module_path)   # 런타임 import
        provider_class = getattr(module, provider_class_name)
        return provider_class(**config)

    @classmethod
    @functools.cache
    def get_supported_providers(cls):
        # providers/ 폴더의 *_provider.py 파일을 스캔해 목록 생성
        provider_files = Path(cls.PROVIDERS_DIR).glob("*_provider.py")
        return {f.stem.replace("_provider", "") for f in provider_files}

핵심 ② 어댑터 패턴 — 변환(in)과 정규화(out)

각 어댑터는 Provider 추상 클래스를 상속해 chat_completions_create 하나만 구현하면 된다. 예를 들어 Anthropic 어댑터의 AnthropicMessageConverter는 OpenAI 형식과 Anthropic 형식 사이를 양방향 통역한다.

핵심 ③ 도구 호출 자동화 — 함수를 넘기면 스키마가 생긴다

OpenAI 도구 호출은 원래 JSON 스키마를 손으로 적어야 한다. aisuite는 docstring-parser로 파이썬 함수의 시그니처와 docstring을 읽어 스키마를 자동 생성한다. max_turns를 주면 "모델 호출 → 도구 실행 → 결과 회신 → 재호출"의 루프까지 라이브러리가 돌려 준다.

def will_it_rain(location: str, time_of_day: str):
    """비가 올지 확인한다.
    Args:
        location (str): 도시 이름
        time_of_day (str): HH:MM 형식 시각
    """
    return "YES"

response = client.chat.completions.create(
    model="openai:gpt-4o",
    messages=[{"role":"user","content":"2시에 소풍 가도 될까?"}],
    tools=[will_it_rain],   # 파이썬 함수 그대로! 스키마 자동 생성
    max_turns=2)            # 도구 왕복 최대 2회까지 자동

5디렉토리 구조 해부

코어 패키지 aisuite/ + 에이전트 + 데스크탑 앱 platform/.

6학습 포인트 (기술별)

멀티 공급자 추상화 라이브러리에서 무엇을 배우나.

A. 동적 플러그인 로딩 — 분기 대신 컨벤션

aisuite는 "확장 가능한 플러그인 시스템을 어떻게 만드나"의 살아 있는 교과서다. 핵심은 ① importlib.import_module로 이름 규칙 기반 동적 로딩, ② 폴더 스캔(glob("*_provider.py"))으로 지원 목록 자동 산출, ③ 추상 베이스 클래스(Provider(ABC))로 계약 강제. 새 기능 추가가 "거대한 if-else 수정"이 아니라 "규칙에 맞는 파일 하나 추가"로 끝난다.

B. 어댑터 패턴 — 차이를 어댑터 안에 가두기

서로 다른 외부 API를 하나의 인터페이스로 묶는 전형적 어댑터/파사드 패턴이다. 배울 점은 "공통 데이터 모델을 먼저 정하고(=framework/), 각 어댑터가 그 모델로 변환/정규화한다"는 방향이다. 호출부는 ChatCompletionResponse라는 한 가지 모델만 알면 된다. 외부 시스템을 여럿 붙이는 모든 통합 작업에 그대로 옮길 수 있다.

C. 코드 재사용 — 상속으로 호환 엔드포인트 흡수

OllamaProvider(OpenaiProvider)처럼, OpenAI 호환 엔드포인트는 어댑터를 새로 안 짜고 OpenAI 어댑터를 상속해 base_url만 교체한다. DeepSeek도 OpenAI SDK를 그대로 쓴다. "호환 표준이 있으면 바퀴를 다시 만들지 말라"는 실용주의의 모범. __init__에서 config를 살짝 손보는 것만으로 새 공급자가 생긴다.

D. 의존성 설계 — optional extras로 가볍게

코어는 무거운 SDK를 강제하지 않는다. pyproject.toml의 [tool.poetry.extras]로 "필요한 공급자만 설치"를 가능하게 했다. 라이브러리 저자라면 반드시 알아야 할 패턴 — 사용자에게 불필요한 의존성을 떠넘기지 않는 것. import 실패 시 친절한 에러로 "pip install 'aisuite[mcp]'"를 안내하는 점도 배울 만하다.

7시스템 / 환경 요구사항

라이브러리는 가볍다 — 진짜 요구사항은 "API 키".

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 동일 코드로 공급자 갈아 끼우기부터 에이전트까지.

9관련 기술 심화 학습 로드맵

6주 코스 — LLM API 기초부터 에이전트 하베스 설계까지.

10핵심 키워드 사전

본문·소스에 나온 용어 빠른 참조.

11참고 링크

• GitHub: andrewyng/aisuite
• PyPI: pypi.org/project/aisuite (pip install aisuite)
• 퀵스타트: Chat Completions · Agents · OpenCoworker
• 기여 가이드: CONTRIBUTING.md (공급자 추가 규칙) · Discord: aisuite
• 관련 개념: Model Context Protocol(MCP)