talhasarit/llm-rate-limiting

LLM 속도 제한

재시도, 스로틀링, 할당량 처리, 동시성 제어를 통해 탄력적인 LLM 통합을 구현하세요. references/examples.md를 읽어 예상 트리거 및 비트리거를 이해하세요. 증상이 정상 경로와 일치하지 않을 때는 references/troubleshooting.md를 읽으세요.

워크플로우

1. 코드베이스를 검사하여 LLM 호출이 애플리케이션을 떠나는 단일 경계를 찾으세요. 호출 지점 전체에 재시도를 분산시키기보다는 하나의 공유 게이트웨이, 클라이언트 래퍼 또는 서비스 모듈을 수정하는 것을 선호하세요.
2. 대상 프로젝트 소스 코드를 분석하여 사용 중인 특정 LLM 제공자를 식별하세요. OpenAI와 Groq를 제공자별 헤더 의미와 제한 모델을 가진 일급 브랜치로 취급하세요.
3. 제공자가 OpenAI인 경우, 할당량, 재시도 동작 또는 속도 조절 가정을 선택하기 전에 references/openai-rate-limits.md를 읽으세요.
4. 제공자가 Groq인 경우, 할당량, 재시도 동작 또는 속도 조절 가정을 선택하기 전에 references/groq-rate-limits.md를 읽으세요.
5. 사용자가 "저는 Tier 1입니다" 또는 다른 요금제 라벨을 제공하는 경우, 제공자 문서가 운영 제한을 완전히 결정하지 않는 한 이를 예산 컨텍스트로만 취급하세요.
6. 프로젝트에 이미 존재하는 기존 추상화, 로깅, 구성 및 테스트 헬퍼를 재사용하세요. 병렬 클라이언트 스택을 도입하지 말고 프로젝트 스타일을 유지하세요.
7. scripts/resilience_templates.py를 읽고 해당 재시도, 재설정 창 및 회로 차단기 패턴을 프로젝트의 HTTP 클라이언트 및 예외 모델에 맞게 조정하세요.
8. 프로젝트에 테스트가 있는 경우 공유 LLM 경계 주변에 회귀 테스트 범위를 추가하거나 업데이트하세요. 정상 경로, 스로틀링 경로 및 제공자별 헤더 구문 분석을 검증하세요.

반응형 처리

반응형 헤더 기반 처리를 구현하세요. Python에서 tenacity 라이브러리를 사용하여 모든 LLM 네트워크 호출을 래핑하세요.

1. Retry-After가 있을 때 먼저 구문 분석하세요.
2. Retry-After가 없는 경우, 지터가 있는 지수 백오프로 폴백하기 전에 제공자의 재설정 헤더를 사용하여 속도를 조절하세요.
3. 지수 지터를 1초에서 60초 범위로 유지하여 급증 스파이크를 방지하세요.
4. HTTP 429 및 503 오류를 명시적으로 처리하세요.
5. 일시적인 5xx, 시간 초과 및 연결 재설정 오류는 주변 호출이 멱등적이거나 반복하기에 안전한 경우에만 재시도 대상으로 취급하세요.
6. 잘못된 요청과 같은 결정적 클라이언트 오류는 재시도하지 마세요.
7. 제공자, 모델, 상태 코드, 재시도 횟수 및 계산된 지연을 포함하는 구조화된 로그를 내보내세요.
8. OpenAI의 경우, x-ratelimit-limit-requests, x-ratelimit-limit-tokens, x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens, x-ratelimit-reset-requests 및 x-ratelimit-reset-tokens를 구문 분석하고 가장 제한적인 차원에 맞춰 속도를 조절하세요.
9. Groq의 경우, retry-after 및 x-ratelimit-* 헤더를 구문 분석하고, 요청 헤더는 RPD를, 토큰 헤더는 TPM을 참조한다는 점을 기억하세요.
10. 재시도 가능한 스로틀링과 재시도 불가능한 할당량 또는 청구 소진을 구분하세요.

회로 차단기

회로 차단기 패턴을 구현하세요. pybreaker 라이브러리를 사용하여 5번 연속 스로틀링 또는 일시적인 서버 오류 후 회로를 열으세요.

1. 400 및 401 클라이언트 오류를 차단기 트리핑에서 제외하세요.
2. 차단기를 재시도 로직과 동일한 공유 LLM 경계에 유지하세요.
3. 차단기가 열려 있을 때 프로젝트별 빠른 실패 예외를 발생시키거나 매핑하여 상위 코드가 정상적으로 저하될 수 있도록 하세요.
4. Groq 플렉스 처리의 경우, capacity_exceeded와 함께 상태 498을 영구적인 애플리케이션 오류가 아닌 재시도 가능한 용량 신호로 취급하세요.

사전 스로틀링

사전 스로틀링을 구현하세요.

1. 대상 API에서 실제로 노출되는 제공자 차원을 추적하는 로컬 클라이언트 측 토큰 버킷 또는 이와 동등한 제한기를 설정하세요.
2. 지터, 클록 스큐 및 동시 작업자를 위한 여유 공간을 확보하기 위해 알려진 임계값보다 약 10% 낮은 유효 처리량을 유지하세요.
3. 제공자가 호출을 거부하도록 두지 말고, 요청 또는 토큰 예산이 충분하지 않을 때 로컬에서 대기열에 넣거나, 지연시키거나, 거부하세요.
4. 애플리케이션에 동일한 예산을 조정해야 하는 여러 작업자 또는 호스트가 있는 경우에만 Redis와 같은 공유 상태를 선호하세요.
5. OpenAI의 경우, 제한을 사용자 수준 제한이 아닌 조직 수준 및 프로젝트 수준 제약 조건으로 취급하세요.
6. OpenAI의 경우, 모든 모델이 독립적인 예산을 가지고 있다고 가정하지 말고 모델 제품군 및 공유 제한 그룹별로 속도 조절 범위를 지정하세요.
7. OpenAI의 경우, 대상 모델이 별도의 긴 컨텍스트 버킷을 사용할 때 긴 컨텍스트 요청 제한을 별도로 고려하세요.
8. Groq의 경우, 제한을 조직 수준 제약 조건으로 취급하고 프로젝트 수준 사용자 지정 제한은 조직 상한선보다 더 제한적일 수만 있다는 점을 기억하세요.
9. Groq의 경우, 캐시된 토큰은 요금 제한에 포함되지 않지만 병렬 트래픽은 여전히 캐시되지 않은 용량을 소진할 수 있다는 점을 기억하세요.

프레임워크 최적화

오케스트레이션 계층이 있는 경우 프레임워크 최적화를 구현하세요.

1. 네트워크 급증을 방지하기 위해 모든 병렬 LLM 실행 경로에 명시적인 max_concurrency 또는 이와 동등한 팬아웃 제한을 적용하세요.
2. 비동기 헬퍼, 작업자 풀, 그래프 러너 및 평가 도구 모음에서 숨겨진 병렬 LLM 호출을 검사하세요.
3. 통합이 모든 호출에 이전 컨텍스트를 계속 추가하여 토큰 예산을 빠르게 소모하는 경우, 무제한 채팅 기록을 자르거나 제한하세요.

캐싱 지침

시맨틱 캐싱 및 제공자별 처리량 튜닝을 권장하세요.

1. 콘솔에서 사용자에게 Redis 기반 시맨틱 캐시 또는 GPTCache를 통합하여 반복되는 외부 호출을 우회하도록 안내하세요.
2. 캐싱을 대기 시간 최적화뿐만 아니라 직접적인 요금 제한 배수(multiplier)로 구성하세요.
3. 출력이 재사용하기에 충분히 안정적인 프롬프트에 대해서만 캐시 삽입을 제안하세요.
4. OpenAI의 경우, max_tokens을 가장 가까운 현실적인 출력 크기로 줄이고 RPM이 포화되고 TPM 여유 공간이 남아 있을 때만 동기 워크로드를 일괄 처리하도록 권장하세요.
5. Groq의 경우, 모델이 지원하고 워크로드가 큰 공유 접두사를 재사용할 때 프롬프트 캐싱을 권장하세요.

구현 규칙

1. 사용자 정의 재시도 루프 또는 차단기 구현보다는 검증된 라이브러리를 선호하세요.
2. 결정적 코드 경로는 자유도를 낮게 유지하세요. 템플릿이 이미 적합할 때 새로운 백오프 공식을 발명하지 마세요.
3. 작성하거나 참조하는 모든 파일 경로에 Unix 스타일의 슬래시를 사용하세요.
4. 제공자 의미를 명시적으로 유지하세요. 한 제공자의 헤더 의미가 다른 제공자에 적용된다고 가정하지 마세요.
5. 정확한 속도 조절이 중요한 경우 실제 헤더, 인증된 제한 페이지 또는 명시적인 사용자 제공 숫자를 사용하세요.
6. 스킬 폴더를 깨끗하게 유지하세요: 설치 가능한 스킬 내부에 README.md, 저장소 전용 문서, 스크린샷을 넣지 마세요.