*jsUdZddlmZddlZddlZddlmZmZmZm Z m Z eje Z dZded<ehdZd Zed d hZej(ZdagZd ed <d,dZd-dZd.dZd/dZd0dZd1dZd2dZd3dZd4dZ d5dZ!d6dZ"d6dZ#d6dZ$ddd d7dZ%ddl&m'Z(ddl&m)Z*Gd d!Z+Gd"d#Z,d8d$Z-d9d%Z.d:d&Z/d;d'Z0ddd( duOpenAI 키 슬롯 브로커 — 1차 키가 죽으면 보조 키로 전환한다 (2026-07-30). ## 왜 있는가 2026-07-29 23:25 `billing_hard_limit_reached` 로 OpenAI 호출이 전부 400 이 되어 콘티 재시도 → 최종 샷 체인이 **전면 중단**됐다. 복구는 사용자가 임시 키를 손으로 넘겨 러너 프로세스 환경변수로만 싣는 수동 조치였다. 단일 키가 장시간 무인 실행의 단일 장애점이라 슬롯을 둘로 늘린다. ## 계약 - **전환 트리거는 키 수준 실패만이다.** billing hard limit / quota 소진 / 401·403 인증. 일반 4xx·5xx·타임아웃·단순 rate limit(429) 은 **건드리지 않는다** — 거기서 키를 바꾸면 멀쩡한 보조 키를 태우고 진짜 원인을 가린다. - **조용한 전환 금지.** 전환은 WARNING 으로 남긴다(어느 슬롯이 왜 죽었고 어디로 넘어갔는지). 슬롯이 다 떨어지면 전환하지 않고 원래 예외를 올린다 — 빈 결과로 흘려보내지 않는다. - **키 값은 어디에도 기록하지 않는다.** 로그에 남기는 것은 슬롯 이름뿐이다. - 전환은 **프로세스 전역**이고 되돌아가지 않는다. 죽은 키로 매 호출마다 다시 찔러 보면 그 자체가 비용이고 지연이다. 새 프로세스는 다시 1차부터. ## 쓰는 쪽 - LiteLLM Router: `active_key()` 로 deployment 를 만들고, 전환이 일어나면 `register_switch_hook` 로 등록한 콜백이 Router 를 무효화한다. - 직접 client: `openai_client()` 가 돌려주는 프록시를 그대로 쓰면 된다. `client.images.edit(...)` / `client.responses.create(...)` 처럼 기존 호출 형태가 그대로 유지되고, 키 수준 실패일 때만 다음 슬롯으로 1회 재시도한다. ) annotationsN)AnyCallableListOptionalTuple))primaryopenai_api_key) secondaryopenai_api_key_secondaryzTuple[Tuple[str, str], ...] SLOT_FIELDS>invalid_api_keybilling_not_activeinsufficient_quotaaccount_deactivatedorganization_restrictedcredit_balance_exhaustedbilling_hard_limit_reached)rzbilling hard limitrzexceeded your current quotazno credits remainingzincorrect api keyrzaccount is not activeiizList[Callable[[], None]] _switch_hookscddl}ddlm}g}tD]C\}}t t ||dxsdj }|s1|j||fEt |jjddxsdj }|r*||Dchc]\}}| c}}vr|jd|f|Scc}}w)u설정된 (슬롯 이름, 키) 목록 — 빈 슬롯은 빠진다. ★환경변수 ``OPENAI_API_KEY`` 는 **최후 슬롯**으로 편입한다 (2026-08-01). 이전에는 존재 판정만 환경변수를 인정하고 실제 키 조회는 인정하지 않아 **약속과 값이 갈라졌다** — ``has_openai_key()`` 는 True 인데 ``active_key()`` 가 ``""`` 라서 preflight 만 통과하고 호출은 빈 키로 나갔다 (직접 재현: ``OpenAIClient._api_key == ''``). 실효 키의 SOT 는 하나여야 한다. 설정 슬롯이 우선이고, 같은 키면 슬롯을 늘리지 않는다(헛 전환 방지). rN)settingsOPENAI_API_KEYenv) osapp.core.configrr strgetattrstripappendenvironget) rroutnamefieldkeyenv_key_ks J/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/openai_keys.pyavailable_slotsr+Vs(!#C" e'(E2.4"5;;=  JJc{ ##"**..!126<"=CCEG7"5A1"55 E7#$ J#6s B>ct}|syt5ttt |dz }ddd|dS#1swYxYw)Nrr+_lockmin _active_indexlenslotsidxs r* active_slotr6osB  E  -Ua0  :a=  AA ct}|syt5ttt |dz }ddd|dS#1swYxYw)uI현재 활성 슬롯의 키. 슬롯이 하나도 없으면 빈 문자열.rr-Nr.r3s r* active_keyr9xsB  E  -Ua0  :a= r7ct}|syt5ttt |dz }ddd|d||dfS#1swYxYw)uA활성 슬롯과 그 키를 **한 값으로** 읽는다. [2026-08-01 A5] 슬롯과 키를 따로 읽으면 그 사이에 일어난 전환이 둘을 어긋나게 한다 — "primary 슬롯에 보조 키가 박힌 클라이언트"가 캐시에 들어가면 그 뒤로는 영구히 잘못된 짝을 쓴다. )Nrr-Nrr.r3s r*active_slot_and_keyr;sQ  E  -Ua0  :a=%*Q- '' s A  Ac(ttSN)r2r+r* slot_countr@s  !!r?c>t5dadddy#1swYyxYw)uJ활성 슬롯을 1차로 되돌린다(테스트·명시 재기동 전용).rN)r/r1r>r?r*resetrBs   sctt5|tvrtj|dddy#1swYyxYw)uY슬롯 전환 직후 호출될 콜백 — 캐시된 클라이언트·Router 무효화용.N)r/rr )fns r*register_switch_hookrEs%  ] "   $ s.7ct|dd}|y |j}t|tr|SdS#t$rYywxYw)uK예외에 실린 응답 본문(JSON) — 없거나 JSON 이 아니면 None.responseN)rjson Exception isinstancedict)excresppayloads r*_response_payloadrOsR 3 D )D |))+!$/79T9 s6 AAcgdfd }|t|dd|t|ddt|ddt|fD]m}t|ts|j d}t|tr|ni|fD]0}||j d||j d2ot S)u,예외에서 OpenAI 오류 식별자를 전부 뽑는다 — `code` 와 `type` 둘 다. ★둘 다 봐야 한다. 2026-07-31 실측에서 크레딧 소진 응답은 code=`credit_balance_exhausted` / type=`insufficient_quota` 로 왔고, 이 모듈이 알던 이름은 **type 쪽에만** 있었다. `code` 하나만 읽던 옛 구현은 그래서 키 수준 실패를 놓쳤다. 본문 모양도 두 가지다 — `{"error": {...}}` 로 감싼 것과 평면 dict (`{"message":…, "type":…, "code":…}`). 둘 다 받는다. cZt|tr|r|vrj|yyyyr=)rJrr )vr#s r*_addz_error_codes.._adds* a ! JJqM)5! r?codeNtypebodyerror)rRrreturnNone)rrOrJrKr"tuple)rLrSsrcerrdr#s @r* _error_codesr^sC fd #$fd #$VT*,=c,BC#t$ ggg$S$/3R#>A v  v ? D :r?c*t|}|r|dSdS)u>가장 구체적인 식별자 하나(없으면 빈 문자열).rr)r^)rLcodess r* _error_coderas  E58$"$r?c8tdt|DS)Nc3,K|] }|tvywr=)_KEY_LEVEL_CODES).0cs r* z&_has_key_level_code..s@.?q$$.?s)anyr^)rLs r*_has_key_level_coderis @l3.?@ @@r?ct|dd}t|tr|r|jdvSt |j xsd}|j dryt|S)u이 예외가 OpenAI 호출에서 났는가. Gemini 쪽 401 로 OpenAI 키를 갈아 끼우는 헛수고를 막는 가드다. litellm 예외는 `llm_provider` 를 실어 주고, openai SDK 예외는 모듈 경로로 알 수 있다. llm_providerN)openaiazure openai_likerrlT)rrJrlowerrU __module__ startswithri)rLprovidermodules r*_is_openai_errorrtsasND1H(C X~~#EEE #Y ! ! 'RF " s ##r?ct|syt|ryt|dd}|tt|dddd}t|tr |t vryt |g}t|dd}t|t r|j|dj|jtfdtDS) u키를 바꾸면 풀릴 수 있는 실패인가. ★단순 rate limit(429)은 **아니다** — 그건 기존 재시도·backoff 의 몫이다. quota 소진이 429 로 오는 경우는 코드(`insufficient_quota` / `credit_balance_exhausted`)나 메시지 문구로 잡는다. 그 둘은 재시도해도 풀리지 않으므로 backoff 에 맡기면 실행 전체가 그대로 죽는다. FT status_codeNrGrV c3&K|]}|v ywr=r>)remtexts r*rgz'is_key_level_failure..s5"4QqDy"4s) rtrirrJint_KEY_LEVEL_STATUSrr joinrorh_KEY_LEVEL_MARKERS)rLstatuspartsraw_bodyrzs @r*is_key_level_failurers C 3 S- .F ~j$7M&#6->#>XJEsFD)H(C  X 99U  ! ! #D 5"45 55r?rwhereattempted_slotc Pt|syt}|Dcgc]\}}| }}}t5ttt dt |dz }|||vr|j|}n|}||kDr-tjd||r||nd|xsd dddy|dzt |k\rFtjd t ||r||dnd|xsdt|dd  dddy|dza|td} ||d} tt} dddtjd   t|xst|dd |xsd|  D] } |  ycc}}w#1swYVxYw#t $rtj#d Y@wxYw)uq키 수준 실패면 다음 슬롯으로 전환한다. 재시도할 슬롯이 있으면 True. False 를 돌려주면 호출자는 **원래 예외를 그대로 올려야 한다** — 여기서 조용히 삼키면 실패가 사라진 것처럼 보인다. ``attempted_slot`` (2026-08-01 A5, Codex 코드 리뷰 BLOCKING 5): **이 호출이 실제로 실패한 슬롯**. 전에는 전역 활성 index 만 보고 판단해서, 같은 슬롯을 잡은 두 호출이 나란히 실패하면 먼저 도착한 쪽이 0→1 로 옮기고 뒤이어 도착한 쪽은 이미 1이 된 전역을 읽어 1→2 로 넘기려 했다. 슬롯이 2개면 그 자리에서 "소진"으로 판정되어 **보조 키를 한 번도 못 써 본 요청이 그대로 버려진다**(4스레드 재현: 3건 유실). 전환은 "지금 전역이 어디인가"가 아니라 "이 호출이 어디서 실패했는가"를 기준으로 판단해야 한다. 다른 호출이 이미 옮겨 놓았으면 **또 옮기지 않고** True 만 돌려준다 — 옮길 필요가 없을 뿐 재시도할 슬롯은 있기 때문이다. Frr-NuOpenAI 키 전환 생략 — %s 는 이미 %s 로 옮겨져 있다 (지점 %s). 이 호출은 옮기지 않고 재시도한다.u없음?Tu^OpenAI 키 슬롯 소진 — 남은 대체 키 없음 (슬롯 %d개, 현재 %s, 지점 %s): %sufOpenAI 키 전환: %s → %s (사유=%s · 지점=%s). 이 프로세스는 이후 %s 슬롯을 쓴다.xuOpenAI 키 전환 훅 실패)rr+r/r0r1maxr2indexloggerinforWrlistrwarningrarI exception) rLrrr4nr(namescur attemptednxtprevhookshooks r* failover_onr s(  $  E !541aQ5E ! -QE Q!78  %.E*A N3II ? KKOec 5r?r*rrQsY#I==r?rc0eZdZdZddZddZd dZd dZy) FailoverOpenAIClientuOpenAI 클라이언트 얼굴을 그대로 쓰되, 키 수준 실패에만 슬롯을 옮긴다. 사용법은 기존과 같다 — `client.images.edit(...)`, `client.responses.create(...)`. 그 외 동작은 원본 클라이언트에 위임한다. c R||_i|_tj|_yr=)_client_kwargs_cache threadingLock _cache_lock)r client_kwargss r*rzFailoverOpenAIClient.__init__hs + $>>+r?cddlm}t\}}|xsd}|j5|jj |}| ||fcdddS|dd|i|j }||j|<||fcdddS#1swYyxYw)u(슬롯 이름, 그 슬롯 키로 만든 클라이언트) — 반드시 짝으로 돌려준다. [A5] 호출자가 나중에 `active_slot()` 을 다시 읽으면, 그사이 다른 스레드가 옮긴 슬롯을 자기가 쓴 슬롯으로 착각한다. r)OpenAInoneNapi_keyr>)rlrr;rrr"r)rr slot_namer&slothitclients r*_rawzFailoverOpenAIClient._rawms ",. 3"F   ++//$'CSy ?C?4+>+>?F &DKK <   s!B&BB c ddlm}dj|}tt dt D]}|j \}}|D]} t|| }||t|r |ddk(rdndtd |t|jd xsd  } ||i|} | | j| cSt!d|d#t$r/} | | j|d t| ||sYd} ~ d} ~ wwxYw)Nrreserve_current_research_call.r-sourceimagesimagellmz openai_keys.modelr)kind granularityrrz raisedru3OpenAI 호출 실패 — 모든 키 슬롯 소진 ())app.core.research_call_budgetrr}rangerr@rr _record_send _GRAIN_SLOTrr"okrIfailedr RuntimeError) rrrrrrr(rtargetpart_send_outrLs r*rzFailoverOpenAIClient._invokes Os1jl+,A99;LD& . * 7!!%$q'X*=g5'%eW-&**W-34 E t.v.$HHJ O-RPQVPWWXYZZ $LLE7'!23"3eDIJ  s&C D %DD cT|jdr t|t||fS)Nr()rqAttributeErrorrrs r*rz FailoverOpenAIClient.__getattr__s( ??3  & &$((r?N)rr)rXzTuple[str, Any])rrrrZrrKrXr)r$rrXr)rrprrrrrrr>r?r*rras ,  $.[`)r?rc <|jddtdi|S)ufailover 가 붙은 OpenAI 클라이언트. `OpenAI(...)` 를 직접 만들던 자리를 이걸로 바꾸면 그 지점이 자동으로 2슬롯을 쓴다. `api_key` 는 브로커가 정하므로 넘기지 않는다. rNr>)popr)rs r* openai_clientrs" i&  0- 00r?cX ddl}|j|ddk(S#t$rYywxYw)ulitellm 자신에게 provider 를 묻는다 — 이름 규칙을 우리가 흉내 내지 않는다. 판정할 수 없으면(가짜 litellm 주입 등) **키를 끼우지 않는다** — 모르는 채로 OpenAI 키를 남의 provider 에 넘기는 것이 더 나쁘다. rNr-rlF)litellmget_llm_providerrI)rrs r*_is_openai_modelrs7 ''.q1X== s  ))c ddl} ddlm}|ddlm}d|d}t |s|||jd d|i|Sd}ttd tD]P}t\}} | s|||jd d|i|cS |||jd || d |cS|J|#t$rYwxYw#t$r} | }t| d |d| sYd} ~ d} ~ wwxYw)uRouter 를 거치지 않는 **직접 litellm 호출**의 유일한 경로. [2026-08-01] production 10개 파일이 ``litellm.completion(...)`` 을 직접 불렀고(13 호출) 전부 기본 모델이 OpenAI 인데 **``api_key=`` 를 하나도 넘기지 않았다.** 그러면 litellm 이 ``os.environ["OPENAI_API_KEY"]`` 로 키를 정하는데, 이 브로커는 그 환경변수를 한 번도 건드리지 않는다 — 즉 보조 슬롯으로 전환돼도 그 호출들은 계속 죽은 1차 키를 쓴다. 환경변수 동기화만으로는 부족하다. 그 경로들은 ``failover_on`` 을 부르지 않아 **전환이 일어날 계기 자체가 없다.** 그래서 여기서 둘 다 한다 — ①활성 슬롯의 키를 명시 전달하고 ②키 수준 실패면 다음 슬롯으로 재시도한다. ★이 함수는 ``llm_client`` 가 아니라 브로커에 있다. 소비자들은 테스트에서 **가짜 litellm 모듈을 sys.modules 에 주입**해 격리하는데, Router 를 최상단에서 import 하는 모듈을 끌어오면 그 격리가 깨진다(실측: ImportError 로 34건 실패). 여기서는 함수 안에서 lazy import 하므로 그 계약이 그대로 유지된다. OpenAI 가 아닌 모델에는 아무것도 끼우지 않는다. 그 경우 ``failover_on`` 이 False 를 돌려주므로 첫 실패에서 그대로 올라간다 — 호출자의 기존 ``num_retries=0`` 계약이 유지된다. rN) _init_opikrzopenai_keys.llm_completion[]rrr-)rrzlitellm.completion[rr>) rapp.modules.llm.llm_clientrrIrrr completionrrr@r;r) rrrrr_wherelastr(rr&rLs r*llm_completionrs3, 9 L*5' 3F E "%V4!w!!8888$(D 3q*,' (() c * 8%7%%r?r*has_openai_keyrs #**, --r?)r fixed_keyc|r||Sd}ttdtD]}t\}} ||cS|J|#t$r}|}t |||sYd}~Ad}~wwxYw)u``fn(api_key)`` 를 활성 슬롯 키로 부르고, 키 수준 실패면 다음 슬롯으로. [2026-08-01 Codex 재리뷰 BLOCKING-2] raw urllib 로 OpenAI 를 직접 부르는 소비자 5곳이 활성 키를 **한 번 복사**했을 뿐 실패를 브로커에 알리지 않았다. ``OpenAIClient`` 는 심지어 **생성 시점**에 복사해 이후 전환이 닿지도 않았다. 그 경로가 그 프로세스의 첫 OpenAI 호출이면 보조 키가 있어도 전환 계기가 없다(직접 재현: Authorization 이 ``Bearer KEY-A`` 한 번뿐, 슬롯 primary 유지). ``fixed_key`` 가 주어지면 **그 키로 한 번만** 부른다 — 호출자가 명시한 키는 고정 계약이므로 우리가 다른 키로 바꿔 부르지 않는다. ``fn`` 이 올리는 예외는 브로커가 OpenAI 호출임을 알아볼 수 있어야 한다 (``llm_provider`` 표시). urllib ``HTTPError`` 는 provider 를 싣지 않아 일반 판정기가 남의 provider 실패와 구분하지 못한다. Nr-r)rrr@r;rIr)rDrrrr(rr&rLs r*call_with_key_failoverr's")}$(D 3q*,' (') c c7N)    J  Ds%EF sA  A0A++A0)rrVc d|_t|tr||_|r/ddl} |j |}t|tr|n||_|S#t $rd}Y(wxYw#t $rY|SwxYw)uraw HTTP 예외를 브로커가 읽을 수 있는 모양으로 표시해 돌려준다. urllib 은 ``llm_provider`` 도 ``status_code`` 도 싣지 않는다. 그대로 두면 ``_is_openai_error`` 가 "OpenAI 호출인지 모름"으로 판정해 **문구 마커까지 가 보지도 못한다.** 표시만 붙이면 기존 판정 계약(코드·상태·문구)이 그대로 적용된다 — 판정 규칙을 여기서 다시 쓰지 않는다. rlrN) rkrJr{rvrHloadsrIrKrV)rLrrV_jsonparseds r*mark_openai_failurerHs # fc "$CO  ! T*",FD!9vtCH J      J s3$A$AA$ A!A$ A!!A$$ A10A1)rXzList[Tuple[str, str]])rX Optional[str])rXr)rXzTuple[Optional[str], str])rXr{)rXrY)rDzCallable[[], None]rXrY)rL BaseExceptionrXzOptional[dict])rLrrXr)rLrrXr)rLrrXr)rLrrrrrrXr)rrrXr)rrrXr)rrrr)rXr)rDzCallable[[str], Any]rrrrrXr)rLrrrrVrrXr)3r __future__rloggingrtypingrrrrr getLoggerrrr __annotations__ frozensetrdr~r|RLockr/r1rr+r6r9r;r@rBrErOr^rarirtrrapp.core.send_ledgerrrrrrrrrrrrrr>r?r*rsX<#77   8 $, (   sCj)  *, ', 2 ("% ::% A$"6>5704> ->9=>H;< = = Q)Q)h1 EP .FH6:&3?BB>B$&!+8r?