46 lines
2.7 KiB
Markdown
46 lines
2.7 KiB
Markdown
# 엔진 게이트웨이
|
|
|
|
API가 `ENGINE_URL`로 호출하는 호스트 실행형 AI 공급자 게이트웨이. Claude CLI 상주 풀과
|
|
Anthropic API, Codex CLI, Agy CLI를 하나의 `/v1/generate`·`/v1/stream` 계약으로 라우팅한다.
|
|
|
|
## 실행
|
|
|
|
```powershell
|
|
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는 키가 없으면 사용할 수 없음으로 표시한다.
|