// tier: helix-primary · order 13

LLMProvider betalicense: TBD

Go (1.25.3)net/http (stdlib)logrustestifyyaml.v3digital.vasic.modelscircuit / health / retry / apikeys / discovery packages43 provider adapters + generic OpenAI-compatible adapter

Source

LLMProvider — one interface · 43 adapters Vendor fan-out Credentials Application Complete / Stream LLMProvider single Go interface 43 provider adapters OpenAI · Anthropic · Gemini … Generic OpenAI-compatible any /v1 endpoint Honest discovery live /v1/models + TTL cache apikeys single credential source Circuit breaker closed→open→half-open Retry backoff + jitter · status-aware
// architecture

하나의 인터페이스, 43개 프로바이더 — 서킷 브레이커, 재시도, 헬스 체크까지 내장.

LLMProvider는 재사용 가능한 Go 모듈로, 통합된 LLMProvider 인터페이스와 이를 둘러싼 프로덕션 레질리언스 패턴(서킷 브레이커, 헬스 모니터링, 백오프 재시도, 지연 로딩)을 정의하며, 하나의 계약 하에 43개의 구체적인 프로바이더 구현체를 제공합니다. 또한 OpenAI 호환 가능한 제네릭 어댑터와 투명한 모델 디스커버리 방식을 지원합니다.

재사용 가능한 Go 모듈로, 하나의 LLMProvider 인터페이스(Complete, CompleteStream, HealthCheck, GetCapabilities, ValidateConfig)와 내결함성 프리미티브(서킷 브레이커, 헬스 모니터, 지터 백오프 재시도, 지연 초기화)를 제공합니다. 43개 프로바이더 어댑터와 OpenAI 호환 제네릭 어댑터를 지원하며, 스레드 안전성을 보장합니다.

LLMProvider는 모든 LLM 소비 서비스가 필요로 하지만 제대로 구축하는 경우가 드문 추상화 계층입니다. 데모와 실제 트래픽에 견디는 시스템을 가르는 지루한 인프라 역할을 합니다. 이 모듈은 단일 기능 기반 인터페이스(Complete, CompleteStream, HealthCheck, GetCapabilities, ValidateConfig)를 정의하여, 애플리케이션 코드가 43개 백엔드 중 어떤 것이 호출에 응답하든 동일한 계약을 타겟팅하도록 합니다. 또한 프로덕션 환경에서 안정적으로 운영할 수 있도록 취약한 프로바이더 호출을 강화하는 운영 레질리언스 기능을 제공합니다.

세 가지 상태(닫힘 → 열림 → 반열림)를 갖는 서킷 브레이커는 모든 프로바이더(스트리밍 채널 포함)를 투명하게 감싸며, 빈 스트림도 실패로 정확하게 카운트합니다. 단일 오동작 프로바이더가 서킷을 트립해 전체 서비스의 다운타임을 방지할 수 있으며, 중앙 CircuitBreakerManager가 모든 브레이커를 추적합니다. 구성 가능한 헬스 모니터는 프로바이더를 임계값 및 간격 기반으로 지속적으로 건강/저하/불량/미확인 상태로 평가하여, 장애가 발생하기 전에 문제를 감지합니다.

재시도 로직은 지수 백오프에 지터를 결합하여 상태를 인식한 결정을 내립니다. 재시도가 의미 있는 오류(429, 5xx, 일시적 네트워크 장애)만 재시도하며, 4xx 오류나 취소된 컨텍스트에는 불필요한 리소스를 소모하지 않습니다. 또한 백오프 지연 시간을 제한하여 재시도 폭풍이 발생하지 않도록 합니다. 지연 초기화 패턴은 각 프로바이더의 구성을 첫 실제 사용 시점까지 지연시켜, 43개 프로바이더 등록에 따른 오버헤드를 최소화합니다.

이 모듈은 43개의 구체적인 프로바이더 패키지와 generic OpenAI 호환 어댑터를 제공합니다. 이 어댑터는 /v1/chat/completions 엔드포인트를 지원하는 모든 프로바이더에 대해 전체 인터페이스를 구현하며, Bearer 인증과 SSE 스트리밍([DONE] 처리 포함)을 완벽하게 지원합니다. 전용 패키지가 없는 벤더라도 어댑터를 해당 URL에 연결하는 즉시 일급 시민으로 활용할 수 있습니다.

자격 증명 관리는 단일 위치(apikeys, 엄격한 ApiKey_<Provider> 규칙 사용)에서 처리되어, "테스트 스위트에서는 하드코딩된 키가 통과했지만 실제 키는 연결되지 않아 프로덕션에서 장애가 발생"하는 유형의 버그를 근본적으로 차단합니다. 모델 디스커버리는 TTL 캐시를 활용해 실시간 프로바이더 API를 조회하며, 과거 하드코딩된 폴백 계층은 의도적으로 삭제되었습니다. 실시간 디스커버리가 실패할 경우 LLMProvider는 오래된 카탈로그 대신 *아무것도 반환하지 않음*으로써, 호출자에게 유효해 보이지만 실제로는 호출할 수 없는 모델 ID를 제공하지 않습니다. 모든 기능은 동시성 사용을 고려해 스레드 안전성을 보장합니다.

콘텐츠

LLM를 단순 호출하면 프로덕션에서 실패합니다. 제공업체가 요청을 제한하거나 성능을 저하시키거나 아예 다운되기도 하며, 한 곳의 문제가 서비스 전체를 무너뜨릴 수 있습니다. 모델 카탈로그도 변동이 잦고, 하드코딩된 목록은 더 이상 작동하지 않는 호출자 ID를 건네줍니다. LLMProvider는 인터페이스, 복원력 패턴, 그리고 신뢰할 수 있는 검색 기능을 중앙화하여 모든 소비자가 내결함성과 정확성을 무료로 상속받을 수 있도록 합니다.

단 한 번의 작업으로 "LLM 제공업체 통합"을 완성합니다. 하나의 인터페이스만 구현하거나, 제네릭 어댑터를 엔드포인트에 연결하기만 하면 됩니다. 그러면 해당 제공업체는 자동으로 서킷 브레이킹, 상태 모니터링, 지터 백오프 재시도 기능으로 감싸집니다. 복원력은 더 이상 각 팀이 (첫 장애 이후 마감 시간에 쫓겨 서둘러) 재발명해야 할 대상이 아니라, 43개 백엔드 모두에 걸쳐 라이브러리의 기본 동작으로 자리 잡습니다. 신뢰성 엔지니어링은 한 번 작성되고 철저히 테스트된 후, 이를 임포트하는 모든 사용자에게 무료로 제공됩니다.

  • 단일 기능 인식 인터페이스 – 완료, 스트리밍, 상태 확인, 기능, 구성 검증이 하나의 계약으로 통합되어 모든 백엔드가 동일하게 준수합니다.
  • 투명한 서킷 브레이커 래핑 – 스트림 포함. 브레이커는 CompleteStream 채널을 보호하며, 단순한 요청/응답뿐만 아니라 빈 스트림도 실제 실패로 간주합니다. 데드락 없이 안전하게 오프락 리스너 알림을 제공합니다.
  • 43개 제공업체 패키지 + 제네릭 OpenAI 호환 어댑터 – 전용 패키지는 경량화되어 있으며, /v1/chat/completions를 지원하는 미등록 벤더라도 어댑터를 연결하는 즉시 작동합니다.
  • 단일 인증 기관(apikeys) – ApiKey_<Provider> 환경 변수를 읽는 곳은 단 한 곳뿐이며, 구조적으로 "테스트는 통과했지만 제품은 실패"라는 불일치를 근본적으로 제거합니다.
  • 정직한 모델 검색(하드코딩된 폴백 없음) – TTL 캐시 뒤에 실시간 제공업체 API가 있으며, 장애 시 nil을 반환합니다. 결코 오래된 또는 조작된 카탈로그를 제공하지 않아 호출 불가능한 ID를 건네지 않습니다.
  • 지연 초기화(sync.Once 사용) – 최초 사용 시까지 생성을 지연시켜, 43개 제공업체를 모두 등록해도 실제로 호출하기 전까지는 거의 비용이 들지 않습니다.
  • 블러핑 방지, 다국어 챌린지 스택 – 실제 러너가 서킷, 상태 확인, 재시도 동작을 다섯 개 지역에서 테스트하며, 뮤테이션 테스팅(변경되지 않은 코드는 반드시 종료 코드 0, 주입된 변이는 종료 코드 99 강제)으로 보호됩니다. 테스트 통과는 검증된 동작을 의미합니다.

  • 연쇄적인 제공업체 장애. 불안정한 백엔드가 서비스 전체를 끌어내리지 않도록 해야 합니다. 해결책은 세 가지 상태(닫힘 → 열림 → 반열림)를 가진 서킷 브레이커로, 모든 제공업체와 그 스트림을 투명하게 감싸고, 지속적인 장애 시 열림 상태로 전환하며, 반열림 상태에서 복구 여부를 탐지합니다. CircuitBreakerManager가 중앙에서 조정합니다.
  • 일시적 오류와 요청 제한. 상태 인식 지수 백오프와 지터를 적용해 재시도 간격을 분산시킵니다. 공식은 min(초기지연·배수^(n-1), 최대지연) ± 지터로, 재시도 요청이 집중되는 '떼지음 현상'을 방지합니다. 재시도 대상은 429, 500, 502, 503, 504 및 네트워크 오류로 한정되며, 취소된 컨텍스트나 기타 4xx 오류에는 재시도하지 않습니다.
  • 등록되었지만 사용되지 않는 다수의 제공업체. 43개 제공업체가 등록되어 있지만 특정 서비스에서는 소수만 활성화되는 경우, 사전 초기화는 낭비입니다. sync.Once로 보호된 지연 초기화를 통해 실제로 호출되는 제공업체만 초기화 비용을 지불하도록 했습니다.
  • 유효하지 않은 모델 ID 제공. 하드코딩된 검색 폴백 계층을 완전히 제거(CONST-036 준수)하고, 실시간 검색 실패 시 아무것도 반환하지 않습니다. 또한 캐시 변조나 동시성 문제를 방지하기 위해 반환 시 방어적 복사를 적용합니다. 정확성은 관례가 아닌 구조로 강제됩니다.
  • 스트리밍과 동시성 정확성. 브레이커의 락과 리스너 콜백 간 데드락이 주요 장애 유형입니다. 해결책은 리스너를 스냅샷으로 캡처하고, 락 해제 후 5초 타임아웃 내에 알림을 전송하며, 재설정 시에도 락을 해제한 상태에서 알림을 보내는 것입니다. 모든 구성 요소는 동시성 사용을 염두에 두고 설계되었으며 -race 스위트로 검증됩니다.

콘텐츠

  • Go (1.25.3) — 최고 수준의 동시성 처리, 정적 바이너리 지원, 강력한 표준 라이브러리를 갖춘 선택; 모듈, 인터페이스, 모든 복원력 프리미티브, 그리고 43개의 어댑터를 포함합니다.
  • net/http (표준 라이브러리) — 의존성 없는 HTTP 구현: 각 공급자 클라이언트, 범용 OpenAI 호환 어댑터, 실시간 검색 호출을 지원하며, 제3자 전송 계층을 감사하거나 패치할 필요가 없습니다.
  • logrus — 구조화되고 레벨 기반의 로깅으로 운영자가 필요한 가시성을 확보: 서킷 브레이커의 상태 전환 및 검색 경로에서 사용됩니다.
  • testify — 테스트 스위트를 구동하며, 특히 변이 브랜치 고정(mutation-branch pinning)을 통해 테스트 성공이 실제 의미를 갖도록 보장합니다.
  • yaml.v3 — i18n 번들 및 설정을 사람이 직접 편집 가능한 형식으로 파싱합니다.
  • digital.vasic.models — 공유되는 LLMRequest / LLMResponse / ProviderCapabilities 타입으로, 모든 어댑터가 동일한 용어를 사용하도록 단일 위치에서 관리됩니다(문서화된 런타임 의존성).
  • 자체 개발 패키지 — circuit, health, retry, apikeys, discovery, providers/(43개 공급업체 + generic), i18n: 복원력과 통합 기능을 작은 단위로 분리하여 독립적으로 테스트 가능하도록 설계되었습니다.
  • .env + ~/api_keys.sh (ApiKey_<Provider> 규칙) — 자격 증명에 대한 명확한 단일 진실 공급원으로, 테스트와 운영 환경에서 동일한 방식으로 키를 관리합니다.
  • Makefile 레이스 스위트(-race -p 1) + 챌린지 러너 — 허위 진단을 방지하는 핵심 요소: 레이스 감지기가 동시성 정확성을 입증하고, 챌린지 러너는 실제 동작을 혼돈, DDoS, 확장, 스트레스, 실시간 검색, 무중단 시나리오로 검증합니다.

  • 상태: 베타. 분리된 재사용 가능한 모듈로, GitHub 저장소는 공개되어 있습니다.
  • 라이선스: 미정. 일관성 없음 — doc.go는 MIT 라이선스를 명시하는 반면, Apache-2.0 스타일의 LICENSE 파일이 존재합니다. 배포 전 반드시 확인하십시오.
  • LLMsVerifier는 표준 모델 카탈로그에 대한 유일한 상위 진실 공급원입니다. helix-deps.yaml 매니페스트는 오래된 상태(문서에는 digital.vasic.models에 대한 의존성이 명시되어 있으나 deps: []로 선언됨)입니다. 검색 기능의 "Tier 2(models.dev)"는 계획된 스텁으로, 현재 활성화되어 있지 않습니다.

우선순위 티어: Helix-기본(LLM-인프라 클러스터 — 분리된 재사용 가능한 모듈). HelixTrack 이후 순위를 가집니다.