AIRGAP StudioAIRGAP Studio

Compatibility Proxy

모델과 클라이언트 간 호환성을 보장하는 게이트웨이 (port 11433)

개요

Compatibility Proxy 는 AIRGAP Studio 의 LLM 소비 익스텐션(airgap-assistant, airgap-lite-assistant, airgap-designer 등) 과 llama-server 사이에 위치하는 Node.js HTTP 게이트웨이 입니다. 일부 모델 (Mistral 등) 의 chat format 차이를 자동으로 정규화하여 어시스턴트가 모델별 차이를 신경 쓰지 않고 동작하도록 합니다.

  • 포트: 11433 (proxy) → forward → 11434 (llama-server)
  • 상태: Phase 6 (2026-04-29 ACCEPTED)
  • 위치: 모든 통신은 loopback (127.0.0.1) 으로 처리되어 에어갭 정책을 준수합니다.

아키텍처

[어시스턴트 익스텐션]
        │
        ▼
http://127.0.0.1:11433/v1   ← Compatibility Proxy (Node.js)
        │
        ▼ (forward + chat format 정규화)
http://127.0.0.1:11434       ← llama-server (Vulkan GPU)
        │
        ▼
   [.gguf 모델]

자동 설정

사용자가 직접 설정할 항목은 없습니다. dev-launcher 와 인스톨러는 어시스턴트의 endpoint 를 자동으로 http://127.0.0.1:11433/v1 로 패치합니다.

  • airgap-assistant (Cline fork): globalStorage 의 openAiBaseUrl 자동 패치
  • airgap-lite-assistant (Continue fork): config 의 endpoint 자동 패치
  • 어시스턴트가 활성화될 때마다 idempotent 하게 다시 패치됨

프로파일 라우팅

모델과 클라이언트 조합에 따라 서로 다른 chat format profile 이 자동 적용됩니다. 매핑 정의는 phase3/models-metadata.json 의 cline.compatProfile 필드입니다.

모델프로파일정규화 동작
Mistral-7B-Instruct-v0.3mistral-strictCline XML 스키마 강제 + 3단계 retry escalation
Meta-Llama-3.1-8Bllama31-passthroughCline XML 스키마 (Plan-only validate)
Qwen3 1.7B / 4B / 8Bqwen3-stripthink-block 제거 후 Cline XML 검증
Granite 4.0 Micropassthrough원본 응답 그대로 전달
모든 모델 + airgap-designer 클라이언트designer-mistralOpenAI tool-calls 스키마로 변환

mistral-strict 프로파일만 응답 검증 실패 시 3단계 retry escalation (stage1_suffix → stage2_few_shot → stage3_temp_zero) 을 수행하며, 모두 실패하면 HTTP 503 + errorCode: model_format_compliance_failed 반환.

환경 변수

변수용도
AIRGAP_PROXY_PORTproxy 리스닝 포트 (기본 11433)
AIRGAP_PROXY_BYPASS=1proxy 전체 우회 — 어시스턴트가 직접 11434 로 연결 (디버깅용)
AIRGAP_DATA_DIRproxy 의 jsonl 로그 / 상태 파일 디렉토리
AIRGAP_LOG_FILEproxy 로그 파일 경로 명시 (기본값: AIRGAP_DATA_DIR 하위)

주의 사항

  • 어시스턴트 설정에서 port 11434 를 직접 지정하지 마세요. dev-launcher 가 매 기동 시 endpoint 를 11433 으로 덮어쓰므로 충돌이 발생합니다.
  • 신규 모델 추가 시 phase3/models-metadata.json 의 cline.compatProfile 필드를 반드시 지정해야 합니다. 누락 시 passthrough 로 폴백되며 일부 어시스턴트에서 응답 품질이 저하될 수 있습니다.
  • proxy 는 https:// upstream forward 를 지원하지 않습니다 (loopback only, 에어갭 정책).

디버깅

proxy 동작을 일시적으로 비활성화하여 문제를 분리하려면:

# proxy 우회 활성화
$env:AIRGAP_PROXY_BYPASS = "1"
# AIRGAP Studio 재시작

문제 해결 후 해당 환경 변수를 제거하고 다시 시작하면 proxy 가 정상 동작 모드로 복귀합니다.

관련 문서