INSTALL.md

Polaris ↔ Star-CLIProxy 설치 가이드

이 문서는 Polaris를 ~/.svtx-cli/에 자체 venv로 설치하고 Star-CLIProxy의 커스텀 플러그인으로 등록하는 절차를 설명합니다.

1. 사전 요건

• Python 3.11+
• uv (또는 python -m venv + pip)
• gcloud CLI + ADC: gcloud auth application-default login
• GOOGLE_CLOUD_PROJECT 환경변수
• Star-CLIProxy 체크아웃 (https://github.com/starhunt/star-cliproxy)

2. Polaris 설치 (~/.svtx-cli/)

# 2-1. 전용 venv 생성
mkdir -p ~/.svtx-cli
uv venv ~/.svtx-cli/.venv --python 3.11

# 2-2. 패키지 설치 (editable — 소스 변경 즉시 반영)
~/.svtx-cli/.venv/bin/pip install -e <이_레포_경로>

# 2-3. 런처 스크립트
cat > ~/.svtx-cli/svtx-cli <<'EOF'
#!/usr/bin/env bash
set -e
SVTX_HOME="${SVTX_HOME:-$HOME/.svtx-cli}"
exec "$SVTX_HOME/.venv/bin/python" -m star_vertex_cli "$@"
EOF
chmod +x ~/.svtx-cli/svtx-cli

# 2-4. 헬스 체크
GOOGLE_CLOUD_PROJECT=<your-project> ~/.svtx-cli/svtx-cli --health
# → ok

3. Star-CLIProxy 플러그인 등록

3-1. 플러그인 파일 복사

이 레포의 examples/cliproxy-plugin-svtx.js와 examples/cliproxy-plugin-svtx.package.json을 Star-CLIProxy 프로젝트의 plugins/cliproxy-plugin-svtx/ 디렉토리에 배치:

mkdir -p <star-cliproxy>/plugins/cliproxy-plugin-svtx
cp examples/cliproxy-plugin-svtx.js \
   <star-cliproxy>/plugins/cliproxy-plugin-svtx/index.js
cp examples/cliproxy-plugin-svtx.package.json \
   <star-cliproxy>/plugins/cliproxy-plugin-svtx/package.json

3-2. config.yaml에 등록

Star-CLIProxy의 config.yaml의 plugins: 섹션에 추가:

plugins:
  - path: "./plugins/cliproxy-plugin-svtx"
    config:
      cli_path: "/Users/<you>/.svtx-cli/svtx-cli"
      default_chat_model: "gemini-2.5-flash"
      default_image_model: "gemini-3-pro-image-preview"
      max_concurrent: 4
      timeout_ms: 240000
      env:
        GOOGLE_CLOUD_PROJECT: "<your-gcp-project>"
        GOOGLE_CLOUD_LOCATION: "us-central1"
        POLARIS_LOG_LEVEL: "info"

3-3. 모델 매핑 등록 (admin API)

ADMIN_TOKEN=<your-admin-token>
for entry in \
  'svtx-flash|gemini-2.5-flash|Polaris Flash' \
  'svtx-pro|gemini-2.5-pro|Polaris Pro' \
  'svtx-imagen-fast|imagen-4.0-fast-generate-001|Polaris Imagen Fast' \
  'svtx-imagen|imagen-4.0-generate-001|Polaris Imagen 4' \
  'svtx-nb-pro|gemini-3-pro-image-preview|Polaris Nano-banana Pro' \
  'svtx-nb|gemini-2.5-flash-image|Polaris Nano-banana'
do
  alias="${entry%%|*}"; rest="${entry#*|}"
  actual="${rest%%|*}"; display="${rest##*|}"
  curl -s -X POST http://localhost:8300/admin/model-mappings \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"alias\":\"$alias\",\"provider\":\"svtx\",\"actual_model\":\"$actual\",\"display_name\":\"$display\"}"
done

3-4. 재시작 + 동작 확인

<star-cliproxy>/start.sh restart

PROXY_KEY=<your-proxy-api-key>

# 채팅
curl -s -X POST http://localhost:8300/v1/chat/completions \
  -H "Authorization: Bearer $PROXY_KEY" -H "Content-Type: application/json" \
  -d '{"model":"svtx-flash","messages":[{"role":"user","content":"안녕"}]}'

# 이미지 (Imagen)
curl -s -X POST http://localhost:8300/v1/images/generations \
  -H "Authorization: Bearer $PROXY_KEY" -H "Content-Type: application/json" \
  -d '{"model":"svtx-imagen-fast","prompt":"a cat","size":"1024x1024"}'

# 이미지 (Nano-banana Pro, 2K — 한글 인포그래픽)
curl -s -X POST http://localhost:8300/v1/images/generations \
  -H "Authorization: Bearer $PROXY_KEY" -H "Content-Type: application/json" \
  -d '{"model":"svtx-nb-pro","prompt":"한글 인포그래픽: ...","size":"2048x2048"}'

4. 모델별 권장사항

모델 alias	용도	비고
svtx-flash	일반 채팅 (저비용)	gemini-2.5-flash
svtx-pro	고품질 추론 채팅	gemini-2.5-pro
svtx-imagen-fast	빠른 일반 이미지	1024² 고정, 사진/일러스트
svtx-imagen	정밀 일반 이미지	Imagen 4 표준
svtx-nb-pro	인포그래픽/한글 텍스트/도표	global endpoint 자동, 기본 2K
svtx-nb	빠른 이미지 + 추론	영문 위주, 한글 약함

5. 운영

업데이트

# Polaris 소스 변경은 editable install로 자동 반영
# 의존성/메타데이터 변경 시:
~/.svtx-cli/.venv/bin/pip install -e <이_레포_경로>

# 플러그인 코드 변경 시:
cp examples/cliproxy-plugin-svtx.js \
   <star-cliproxy>/plugins/cliproxy-plugin-svtx/index.js
<star-cliproxy>/start.sh restart

응답 모드 (url vs b64_json)

플러그인은 기본적으로 url(file://) 모드로 응답합니다 — LLM 에이전트 호출자의 컨텍스트 토큰 비용(b64는 1장당 수십만 토큰)을 보호합니다.

// 기본 — file:// URL (~120 bytes 응답)
{"model":"svtx-imagen-fast","prompt":"...","n":1,"size":"1024x1024"}

// b64 강제 — 인라인 base64 (~700KB+ 응답)
{"model":"svtx-imagen-fast","prompt":"...","response_format":"b64_json"}

캐시 디렉토리: ~/.svtx-cli/cache/ (24h TTL 자동 청소).

중요: Star-CLIProxy 본체의 response_format 패스스루 패치가 적용되어 있어야 b64 옵트인이 작동합니다. 패치는 단순 3개 필드 추가:

• packages/shared/src/types/provider.ts ExecuteOptions에 responseFormat?, n?, size? 추가
• packages/server/src/routes/v1/images-generations.ts:136 execute 호출에 responseFormat: body.response_format, n: body.n, size: body.size 3줄 추가

(이 레포 README 하단의 "Star-CLIProxy 패치" 섹션 참고)

트러블슈팅

• --health가 fatal: ADC 없음 → gcloud auth application-default login
• 호출 시 model_not_found: model_mapping 미등록 → 3-3 단계 재실행
• Pro 모델 호출 시 404: location이 us-central1로 갔음 → 플러그인이 자동으로 global 적용. 수동 호출 시 요청에 "location":"global" 명시.
• 한글 텍스트 깨짐: image_size: "2K" 또는 "4K" 사용 (Pro 모델만). 플러그인 기본은 2K.
• response_format: "b64_json" 보냈는데 url로 옴: Star-CLIProxy 본체 패치 미적용 (위 참고).