experiential 딥다이브
— 여러 모델 호출을 한 API로 받아 예산·가드레일·기록을 붙이는 게이트웨이

1프로젝트 한줄 요약

experiential은 호스팅·BYOK(자기 키)·로컬 모델을 하나의 OpenAI 호환 API 뒤에 모으고, 사용자·에이전트별 모델 권한과 월 예산을 걸며, 지나간 트래픽으로 라우터를 최적화하는 오픈소스 게이트웨이입니다. README는 이 세 가지를 프로젝트의 목적으로 직접 적습니다.

설치는 pip install experiential, 실행 명령은 exp입니다(pyproject.toml의 [project.scripts]가 exp = "exp.cli:main"을 가리킵니다). 이 글은 커밋 c847e2a(버전 0.7.178) 소스를 읽기만 하고 설치·실행하지 않은 결과이며, 명령의 실제 동작은 소스와 문서 설명 기준입니다.

1-1. 명령어 일곱 개가 전부다

AGENTS.md는 루트 CLI 명령 집합이 정확히 build, capture, config, eval, login, optimize, run 일곱 개라고 못 박고, 테스트(exp/cli/app_test.py)가 이를 강제한다고 적습니다. 인자 없이 exp만 치면 홈 화면이 열립니다.

핵심은 게이트웨이(exp run) 하나만 써도 가치가 있고, 학습형 라우팅(build→optimize)은 그 위에 얹는 선택 기능이라는 점입니다.

2왜 주목받는가

이번 분석 대상은 TrendShift 트렌딩 15위로 선정된 항목입니다. 스타 수 같은 외부 수치는 이 글에서 직접 확인하지 않았으므로 적지 않습니다. 소스에서 확인되는 것은 개발 활동입니다. 고정한 커밋 시점에 이력이 842개 커밋이고, 마지막 커밋 날짜는 2026-10-09, 커밋 제목에 버전 0.7.178이 붙어 있으며 릴리스 목록에는 v0.7.178·v0.7.177·v0.7.175가 보입니다.

2-1. 비슷한 “LLM 프록시”와 다른 점

또 하나 눈에 띄는 점은 저장소의 엄격함입니다. AGENTS.md는 새 소스 파일을 1,000줄 미만으로 유지하고, Ruff 포맷·린트와 ty 타입 검사를 전체 저장소에서 통과해야 하며, 패키지 간 import 방향(common→runtime→simulation→optimize→cli)을 AST 검사로 강제한다고 적습니다. 테스트 파일(*_test.py)이 601개입니다.

3기술 스택 전체 지도

고정 커밋에서 git ls-files 기준 추적 파일은 1,536개입니다. 확장자별로는 Python 1,269개, Rust 183개, 마크다운 52개가 대부분입니다. 물리 줄 수는 Python 약 43.9만 줄(테스트 포함), Rust 약 7.4만 줄입니다. 줄 수에는 테스트·주석·빈 줄이 섞여 있으니 규모 감각으로만 보세요.

3-1. 백엔드(실행부)

3-2. 프론트엔드·인프라

이 저장소에는 웹 프런트엔드가 없습니다. 대시보드는 호스티드 Platform(platform.experientiallabs.ai)이 맡고, 로컬에서는 GET /usage·/usage.json이 내용 없는 사용량 집계를 보여 줍니다. CI는 .github/workflows/의 gate.yml(전체 품질·구조 검사), gateway-latency.yml(지연 배지), python-package.yml 세 개입니다.

3-3. 선택 의존성

• sft 추가 기능: tinker·tinker-cookbook (미세조정)
• dev 추가 기능: pytest·pytest-xdist·ruff·ty·maturin·websockets 등
• 캡처 엔진은 Python 3.13+에서만 설치되는 mitmproxy 포크(exp-mitmproxy)에 의존

4아키텍처 심화 분석

docs/reference/gateway-architecture.md가 설명하는 구조를 단순화하면 아래와 같습니다. 요청이 밖으로 나가기 전에 인증→권한→예산 예약이 끝나야 하고, 응답이 끝난 뒤에 정산(settle)이 일어납니다.

4-1. 핵심 설계 패턴

• 가상 키와 지문 저장. 가상 키는 후추(pepper)를 섞은 지문만 저장하고 원문은 발급 시 한 번만 보여 줍니다. 제공자 설정에는 환경변수 이름만 저장하고 값은 저장하지 않습니다.
• fail-closed. 비활성 사용자, 폐기·만료된 키, 제거된 grant, 별칭 리비전 변경은 모두 요청을 거부합니다. 구성이 비어 있으면 서버가 기동 시 어떤 별칭이 문제인지 이름을 대며 실패합니다.
• 물리 호출 단위 예약. 한 요청이 여러 배포를 거칠 수 있으므로 호출마다 start_attempt로 예약하고 결과를 정산합니다. 재시도와 failover도 이 단위로 기록됩니다.
• failover 규칙. 배포마다 failover_only_on에 실패 종류(throttled, timeout, refusal:cyber_policy 등)를 적으면 그 실패 뒤에만 쓰이는 대기 자리가 됩니다.
• 불변 계약 객체. 정책·결정·예산 범위는 Pydantic 모델이며 생성 시점에 모순을 거부합니다(아래 코드).

4-2. 예산 범위의 검증 코드

exp/runtime/gateway/budgets.py는 월 한도의 범위를 네 가지로 제한하고, 종류마다 있어야 하는 식별자 조합을 검사합니다.

class BudgetScopeKind(StrEnum):
    TEAM = "team"
    IDENTITY = "identity"
    POOL = "pool"
    DEPLOYMENT = "deployment"

# _require_scope_shape 안의 기대 조합 (identity_id, alias_id, pool_id, deployment_id)
expected = {
    BudgetScopeKind.TEAM:       (False, False, False, False),
    BudgetScopeKind.IDENTITY:   (True,  False, False, False),
    BudgetScopeKind.POOL:       (False, True,  True,  False),
    BudgetScopeKind.DEPLOYMENT: (False, True,  True,  True),
}[self.kind]
if present != expected:
    raise ValueError(f"{self.kind.value} budget scope has invalid identifiers")

“팀 한도에 사용자 ID가 섞여 들어오는” 설정 실수가 저장 단계에서 걸러지는 방식입니다.

4-3. 가드레일 파이프라인

가드레일은 선택 기능이며 기본은 꺼짐입니다. 조직·사용자별 GuardrailPolicy를 켜면 요청마다 GuardrailSession이 정책을 한 번 고정하고, 입력 검사→(재작성)→출력 검사를 같은 파이프라인으로 돌립니다. 소스 문서에서 확인되는 특징은 아래와 같습니다.

• 플랫폼 정책이 사용자 정책보다 먼저 실행되고, 사용자 지정 정책은 플랫폼 검사를 끄지 못합니다.
• mode="observe"는 차단·재작성 없이 입력만 관찰하며, 큐가 차면 “허용”이 아니라 skipped로 기록합니다.
• 임베딩·이미지 생성·Decisions 엔드포인트는 아직 이 검사를 통과시킬 수 없어서, 적용되는 강제 정책이 있는 사용자의 호출은 이 엔드포인트에서 거부됩니다.

4-4. 학습형 라우터: 보수적인 kNN

exp/common/routing/policy.py의 KnnRouterPolicy는 후보 모델 목록, 기준(baseline) 모델, 임베딩 모델, 학습에 쓴 번들의 해시, KnnGuard 임계값을 한 객체에 묶어 동결합니다. 요청의 “첫 사용자 의도·초기 컨텍스트·도구·허용 태그”만 특징으로 쓰고(request-visible-v2), 결정 기록(RoutingDecision)에는 이웃 수·짝지은 관측 수·fallback_reason이 남고, 임베딩 호출이 실패하면 동결된 보수적 기준 모델을 씁니다. 검증에 쓰는 관측 수는 최소 8개 이상이어야 합니다(minimum_paired_observations ≥ 8).

5디렉토리 구조 해부

규칙 하나가 구조를 지탱합니다. AGENTS.md에 따르면 common은 runtime·simulation·optimize·cli를 import할 수 없고, runtime은 simulation 이상을, simulation은 optimize·cli를 import할 수 없습니다. 이 방향이 AST 검사로 닫혀 있어 순환이 생기지 않습니다.

6학습 포인트 (기술별)

7하드웨어 / 시스템 요구사항

GPU는 요구 사항에 나오지 않습니다. 이 프로젝트는 모델을 직접 돌리지 않고 호출을 중계하며, 미세조정은 외부 서비스(Tinker)에 맡깁니다.

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

8-1. 입문 ★ 로컬 게이트웨이 띄우고 한 번 호출하기

pip install experiential
exp                       # 처음이면 설정 마법사: 제공자, 별칭, 한도, 키 발급

export EXP_GATEWAY_KEY=...   # 마법사가 한 번 보여 주는 키
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $EXP_GATEWAY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"opus-5","messages":[{"role":"user","content":"Help me"}]}'

별칭 opus-5는 README 예시이며, 실제로는 마법사에서 정한 이름을 씁니다. 확인할 것: 응답과 GET /usage 집계가 일치하는지.

8-2. 초급 ★★ 호출자 시점으로 점검하기

같은 게이트웨이에서 아래 명령으로 호출자가 보는 것을 확인합니다. 저장된 상태가 없고 HTTP 요청만 보냅니다(docs/usage.md).

exp config gateway models --json      # 내 키에 허용된 별칭 목록
exp config gateway key check --json   # 키 유효성 (키를 저장하지 않음)
exp config gateway call opus-5 "한 줄로 자기소개"

8-3. 중급 ★★★ 월 예산을 낮추고 거부되는 모습 보기

exp config gateway ...의 월 한도 명령으로 아주 작은 한도를 걸고, 호출이 어떤 오류로 막히는지 응답 본문과 /usage.json을 비교합니다. 이어서 budgets.py의 BudgetScope 검증 코드를 읽고 네 범위 중 어디에 걸렸는지 맞춰 보세요.

8-4. 고급 ★★★★ 공개 트레이스로 라우터 만들기 흐름 따라가기

README가 안내하는 공개 데이터셋을 받아 exp build를 돌립니다. 비용이 드는 단계는 비용 확인 화면에서 멈추므로, 먼저 --dry-run(문서에 따르면 유료 호출 0회)으로 흐름만 확인하세요. 단, dry run은 대화형 설정을 건너뛰므로 models.toml에 제공자 연결과 모델 별칭, world_model·judge·embedder 세 역할이 미리 설정돼 있어야 합니다. 없으면 model configuration is incomplete before build 오류로 끝나니, 먼저 exp config providers로 구성하세요(app.py _load_or_setup_catalog). 앞의 exp config gateway 실습과는 다른 설정입니다.

curl -L -o traces.otel.jsonl \
  https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces/resolve/540883e451dc13d34fb50fdd36b143cb0f1fb0db/traces.otel.jsonl
exp build support-agent --traces traces.otel.jsonl --source otlp --dry-run

--dry-run만 쓰면 입력이 없어 BadParameter로 끝납니다. 소스 exp/cli/build/app.py가 dry run과 자동화 실행에는 -t/--traces PATH 또는 --import-id ID를 요구하고(208-213줄), docs/usage.md도 자동화에서는 --traces와 --source를 함께 주라고 안내합니다. otlp는 CANONICAL_TRACE_SOURCES에 있는 소스 이름이며 생략해도 기본값입니다(257줄). 이 명령을 직접 실행해 확인하지는 않았습니다.

그다음 optimize/router/fit/workflow.py와 common/routing/policy.py를 열어 “정책 객체에 무엇이 묶이는가”를 정리해 보세요.

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

10핵심 키워드 사전

11참고 링크

11-1. 저장소

• experientiallabs/experiential · README
• docs/usage.md — 명령어와 동작 표
• gateway-architecture.md · gateway-guardrails.md · gateway-failover-rules.md
• local_gateway_traffic.md — 로컬 캡처와 exp build --source gateway
• exp/common/routing/policy.py · exp/runtime/gateway/budgets.py
• AGENTS.md — 저장소 규칙
• LICENSE (Apache 2.0 전문) · 네이티브 크레이트 Cargo.toml도 Apache-2.0

11-2. 관련 공식 자료

• Experiential Platform 문서 — 호스티드 게이트웨이
• OpenAI Chat Completions 문서 · Anthropic Messages API
• uv 문서 · Pydantic 문서
• PyO3 가이드 · axum 문서 · tokio 튜토리얼
• OpenTelemetry 문서

외부 문서는 바뀔 수 있습니다. 이 글의 파일 경로와 동작 설명은 커밋 c847e2a에 맞춘 것입니다. 소스에서 확인하지 못한 항목(스타 수, 실제 라우팅 성능, 호스티드 서비스의 운영 방식)은 적지 않았습니다.

현재 상태 (2026-10-25 확인)