yunchan/vignette
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
vignette/apps/api/engine_gateway
History
Yun Chan 4771b97c3a 엔진 readiness 실패 캐시 TTL 분리와 프로브 타임아웃 보정 
공개 런타임에서 reasoning_effort=high 콜드 프로브 1회가 20초를 넘기면
실패가 성공과 같은 TTL(운영 1800초)로 캐시되어 공개 API가 최장 30분간
engine=false로 오염되고, 워치독은 기본 /ready의 캐시된 200만 보고 API만
재시작하는 무한 루프에 빠졌다(2026-08-18 06:30 KST 실측).

- 실패 항목 전용 ENGINE_READY_FAILURE_TTL_SECONDS(기본 30초)를 분리해
  복구가 프로브 한 번 안에 감지되게 하고, 진짜 장애 중 프로브 폭풍은
  실패 TTL이 계속 막는다.
- ENGINE_READY_TIMEOUT_SECONDS 기본값을 20→45초로 올려 고효율 콜드
  스폰의 정상 지연을 장애로 오판하지 않는다.
- 회귀 4건 신설(실패 재프로브·성공 캐시 유지·실패 폭풍 억제·기본값 계약),
  게이트웨이 62/62·API 전체 986 passed·ruff clean.
2026-08-18 10:45:35 +09:00
..
golden feat: 운영 안정성과 세션 음성 경험 개선 2026-07-31 00:13:08 +09:00
__init__.py feat(engine): claude -p 상주 멀티턴 엔진 게이트웨이 + 실동작 검증 2026-06-25 21:43:27 +09:00
gateway.py 엔진 readiness 실패 캐시 TTL 분리와 프로브 타임아웃 보정 2026-08-18 10:45:35 +09:00
provider_registry.py G0~G8 성과·동맹 측정 OS 작업 일괄 고정 2026-08-08 01:30:53 +09:00
README.md feat: 운영 안정성과 세션 음성 경험 개선 2026-07-31 00:13:08 +09:00
requirements.txt G0~G8 성과·동맹 측정 OS 작업 일괄 고정 2026-08-08 01:30:53 +09:00
test_gateway_model.py G0~G8 성과·동맹 측정 OS 작업 일괄 고정 2026-08-08 01:30:53 +09:00
test_provider_registry.py G0~G8 성과·동맹 측정 OS 작업 일괄 고정 2026-08-08 01:30:53 +09:00
test_ready_cache.py 엔진 readiness 실패 캐시 TTL 분리와 프로브 타임아웃 보정 2026-08-18 10:45:35 +09:00

README.md

엔진 게이트웨이

API가 ENGINE_URL로 호출하는 호스트 실행형 AI 공급자 게이트웨이. Claude CLI 상주 풀과 Anthropic API, Codex CLI, Agy CLI를 하나의 /v1/generate·/v1/stream 계약으로 라우팅한다.

실행

cd apps\api
python -m uvicorn engine_gateway.gateway:app --host 127.0.0.1 --port 9099

공급자와 모델 탐색

공급자 모델 원천 기본값 실행 방식
claude_cli CLI가 목록 명령을 제공하지 않아 공식 alias 정적 목록 CLI 기본 / High 기존 claude -p 상주 풀
claude_api Anthropic GET /v1/models API 목록 첫 모델 / 지원 effort Messages API
codex_cli Codex app-server model/list gpt-5.6-terra / Medium 격리 cwd의 ephemeral codex exec
agy_cli agy models gemini-3.6-flash-high / High 격리 cwd의 agy --print --output-format stream-json
openai, solar 현재 어댑터 없음 없음 사용할 수 없음으로 명시

모델 목록은 60초 캐시하며 관리자가 강제 새로고침할 수 있다. 저장할 때 선택한 공급자·모델·추론 강도를 게이트웨이가 다시 검증하므로 임의 문자열이나 사용할 수 없는 조합은 운영값으로 들어가지 않는다.

API

  • GET /health — 얕은 프로세스 liveness
  • GET /ready?provider=&model=&reasoning_effort= — 선택 조합으로 실제 생성 readiness 확인
  • GET /v1/capabilities?provider=&force= — 모델·추론 강도 카탈로그
  • POST /v1/generate — 단발 생성
  • POST /v1/stream — SSE token/done/error; Claude CLI partial-message delta와 Agy stream-json delta를 실시간 전달
  • /session 계열 — 명시 생성 없이도 첫 client stream에서 자동 바인딩되는 Claude CLI 회기별 상주 프로세스 풀

환경변수

  • CLAUDE_BIN, CODEX_BIN, AGY_BIN — CLI 경로. Windows Codex는 npm shim보다 실제 native exe를 우선 탐색한다.
  • ANTHROPIC_API_KEY, ANTHROPIC_API_BASE — Anthropic 모델 조회·Messages API.
  • ENGINE_CLI_CWD — Codex/Agy 격리 작업 폴더. 기본은 시스템 임시 폴더의 vignette-engine-runtime.
  • ENGINE_CAPABILITY_CACHE_TTL_SECONDS — 모델 카탈로그 TTL, 기본 60초.
  • ENGINE_CLI_TIMEOUT_SECONDS — CLI 생성 상한, 기본 300초.
  • ENGINE_MODEL, ENGINE_FALLBACK_MODEL, SESSION_BUDGET_USD — 기존 Claude CLI 풀 설정.

Windows의 Agy는 --print 프롬프트가 명령줄 인자여서 24,000자를 넘는 요청을 fail-closed한다. 대화 conversation id는 로컬 저장·삭제 수명주기 계약이 없어 재사용하지 않고 stateless stream으로 실행한다. Anthropic API는 키가 없으면 사용할 수 없음으로 표시한다.