API 안정성 정책

이 페이지는 LiteLLM Proxy HTTP API의 어느 부분이 보존하려 노력하는 공개 계약(public contract)이고, 어느 부분이 언제든 바뀔 수 있는 비공개인지 정의해요.

OpenAPI 스펙이 공개 API

프록시의 OpenAPI 스펙에 나타나는 모든 엔드포인트는 공개입니다. 스펙은 /openapi.json에서 제공되고 기본적으로 /에서 Swagger UI로 렌더링됩니다 (DOCS_URL로 설정 가능, UI settings 참고). 공개 엔드포인트에 대해서는 동작 계약을 유지하려 노력합니다: 경로와 HTTP 메서드, 요청·응답 형태, 인증 요구사항, 기본 동작.

추가적(additive) 변경은 breaking이 아니며 어떤 릴리스에서든 배포할 수 있어요: 새 엔드포인트, 새 선택적 요청 필드, 새 응답 필드. 클라이언트는 인식하지 못하는 응답 필드를 무시해야 합니다. 필드를 제거하거나 이름을 바꾸는 변경, 기본값 변경, 엔드포인트 호출 권한을 좁히는 변경, 또는 기존 동작을 유지하려면 조치가 필요한 변경은 breaking change예요. Breaking change는 해당 버전의 릴리스 노트 맨 위에 전용 Breaking Changes 섹션에서 알리며, 릴리스 주기 버전 규칙을 따릅니다.

그 외 모든 것은 비공개

OpenAPI 스펙에 없는 모든 엔드포인트는 비공개예요. 이 라우트는 LiteLLM Admin UI 또는 내부 프록시 요구를 위해 존재합니다. 코드베이스에서는 라우트 정의의 include_in_schema=False로 스펙에서 숨겨집니다. /login, /v2/login, /fallback/login이 예시예요. 비공개 엔드포인트는 통지 없이 어떤 릴리스에서든 요청·응답 형태를 바꾸거나, 동작을 바꾸거나, 제거될 수 있으며, 위의 breaking change 프로세스에 포함되지 않아요.

비공개 엔드포인트를 상대로 통합을 구축하지 마세요. 오늘 비공개 엔드포인트만 제공하는 기능이 필요하다면, 지원되는 공개 엔드포인트로 노출될 수 있도록 사용 사례를 설명하는 GitHub 이슈를 열어 주세요.

내 버전에서 공개된 것 확인하기

스펙은 실행 중인 프록시에서 생성되므로 배포한 버전을 정확히 반영해요. 공개 경로를 나열하려면:

curl -s http://localhost:4000/openapi.json | jq '.paths | keys'

NO_DOCS 또는 NO_OPENAPI 설정(환경 변수 참고)은 프록시가 Swagger UI나 /openapi.json을 제공하지 못하게 하며, 어느 엔드포인트가 공개인지는 바꾸지 않아요. 해당 플래그가 없는 프록시에서, 또는 같은 버전을 로컬로 실행해 스펙을 가져와 공개 표면을 확인하세요.

출처: 문서

더 알아보기 (Learn more)

Release Cycle: 버전을 어떻게 번호 매기고 major, minor, patch 증가가 무엇을 의미하는지
Migration Policy: 베타 기능이 Enterprise로 이동할 때 무슨 일이 일어나는지