Databricks LLMOps ① AI Gateway — LLM 폴백·게이트웨이 프록시·Inference Table 로깅

📚 시리즈 — Databricks LLMOps

• ① AI Gateway — LLM 폴백·게이트웨이 프록시 — 현재 글
• ② Prompt Registry — 프롬프트 버전·alias 관리
• ③ MLflow Tracing — LangGraph 관측·PII 마스킹

 

 

 

1. 개요

Mosaic AI Gateway 는 Model Serving 엔드포인트 앞단에서 생성형 AI 호출을 거버넌스·관측·제어 하는 계층입니다. 엔드포인트의 ai_gateway 설정으로 켜며, 사용량 추적·페이로드 로깅(inference table)·레이트 리밋·가드레일·폴백·트래픽 분배를 제공합니다.

본 가이드는 서울 리전(ap-northeast-2) 기준이며, A항공 RAG 서울 리전 검증 워크스페이스(dbc-xxxxxxxx-xxxx)에서 실제 검증한 내용을 토대로 LLM 폴백(Fallbacks) 구성과 Inference Table(페이로드 로깅) 의 설정·저장 내용, 그리고 RAG 에이전트가 게이트웨이를 LLM 으로 사용하는 소스·배포 패턴을 다룹니다.

상태: Fallbacks·Inference Table·Usage tracking·Rate limit 은 GA. AI Guardrails 는 서울 리전 미지원(§2).

 

2. 핵심 개념

기능	설명
Fallbacks	1순위 모델 실패(429/5XX) 시 다음 모델로 자동 전환. external model 전용(§3)
Inference table (payload logging)	요청/응답 원문 페이로드를 UC Delta 테이블(<prefix>_payload)에 비동기 적재 (§5)
Usage tracking	토큰 수·요청 수를 system.serving.endpoint_usage·system.serving.served_entities 시스템 테이블에 적재
Rate limits	분당 쿼리(QPM)·토큰(TPM) 제한을 endpoint·user·group 레벨로 설정
Traffic splitting	served entity 간 트래픽 비율 분배(A/B·점진 배포)
AI Guardrails	Safety·PII 탐지(Block/Mask). 서울 미지원

적용 대상 엔드포인트 타입에 따라 지원 기능이 다릅니다 — Fallbacks 는 external model 엔드포인트에만 적용되고, 나머지(usage tracking·inference table·rate limit)는 custom/FM 엔드포인트에도 적용됩니다.

서울 리전 제약 — AI Guardrails 미지원: 위 기능 중 AI Guardrails(Safety·PII 탐지) 만 서울 리전(ap-northeast-2)에서 지원되지 않습니다 — put-ai-gateway 가 "AI Guardrails is not currently supported for this endpoint type in this workspace" 로 거부합니다. 가드레일 모더레이션이 Foundation Model API pay-per-token 모델에 의존하는데, 공식 문서상 "cross-geo 활성화가 필요한 리전은 Guardrails 미지원" 이며 서울이 이에 해당하기 때문입니다. 나머지(Fallbacks·Inference table·Usage tracking·Rate limits·Traffic splitting)는 서울에서 정상 동작합니다.

 

3. LLM 폴백 구성 (External Model 프록시)

 

3.1 왜 별도 프록시 엔드포인트인가

• Fallbacks 는 external model 엔드포인트에만 지원됩니다. RAG 에이전트는 custom-model(ResponsesAgent) 엔드포인트라 그 자체 에는 폴백을 걸 수 없습니다.
• 따라서 external model 2개(main·backup)를 묶은 프록시 엔드포인트를 따로 만들고, 에이전트가 이 프록시를 LLM 으로 호출하게 합니다. 폴백은 프록시 내부에서 자동 처리됩니다.
• 워크스페이스 자신의 FM 엔드포인트를 databricks-model-serving provider 로 self-참조 하므로 전용 SP 토큰(secret)이 필요합니다(§3.2.1).

[RAG agent (custom model)] → [ke-airag-llm-gw (external model + fallback)]
                                  ├─ main:   Gemini 3 Flash (100%)
                                  └─ backup: Claude Sonnet 4.6 (0% = 폴백 전용)

 

3.2 구성

게이트웨이는 두 단계로 만듭니다 — (1) self-참조 호출에 쓸 SP 토큰(secret) 준비(§3.2.1), (2) Gemini·Sonnet 두 모델을 단 custom serving endpoint 생성(콘솔 §3.2.2 또는 CLI §3.2.3). 콘솔·CLI 어느 경로든 같은 secret 을 참조합니다.

중요: Gemini·Claude 는 built-in Foundation models 목록(Llama·Gemma·GPT OSS·Qwen 등)에 없습니다. 워크스페이스의 databricks-gemini-3-flash·databricks-claude-sonnet-4-6 을 쓰려면 External model provider = Databricks Model Serving(self-참조) 로 추가하며, 이때 Databricks API secret(토큰) + Workspace URL 이 필수입니다. 그래서 §3.2.1 SP 토큰이 선행물입니다.

3.2.1 SP 구성 (self-참조 토큰)

self-참조 자격은 개인 PAT 가 아니라 전용 Service Principal 토큰을 씁니다. 토큰은 사용 여부와 무관하게 발급 시 정한 수명이 지나면 만료되므로 만료 전 갱신이 필요합니다 — 이 워크스페이스의 토큰 수명 상한은 730일(2년) = 63072000초 입니다. 따라서 2년(상한값) 발급 + 만료 전 정기 로테이션을 씁니다. 아래를 신규/갱신으로 구분합니다.

(A) 신규 구성 — SP 생성 + 토큰 권한 부여 + OBO 토큰(2년) 발급 + secret 저장:

PROF=<profile>
# 1) 전용 SP 생성 → applicationId(=client_id, SCIM id 아님) 확보
SP_APP_ID=$(databricks service-principals create --display-name airag-llm-gw-sp -p $PROF -o json | jq -r .applicationId)
# 2) SP 에 토큰 사용 권한(CAN_USE) 부여 (admins 유지)
databricks token-management update-permissions -p $PROF \
  --json "{\"access_control_list\":[{\"group_name\":\"admins\",\"permission_level\":\"CAN_MANAGE\"},{\"service_principal_name\":\"$SP_APP_ID\",\"permission_level\":\"CAN_USE\"}]}"
# 3) secret scope 준비
databricks secrets create-scope airag_llm_gw -p $PROF
# 4) SP OBO 토큰(2년) 발급 → 바로 secret 저장 (콘솔·CLI 가 이 secret 참조)
databricks secrets put-secret airag_llm_gw token \
  --string-value "$(databricks token-management create-obo-token "$SP_APP_ID" --lifetime-seconds 63072000 --comment "airag-llm-gw self-ref" -p $PROF -o json | jq -r .token_value)" -p $PROF

(B) 토큰 갱신 (만료 전 로테이션) — SP 는 재생성하지 않고 기존 SP 로 새 토큰만 발급해 secret 을 덮어씁니다(토큰 CAN_USE 는 이미 부여됨):

PROF=<profile>
# 1) 기존 SP applicationId 조회 (신규 셸 기준; SP_APP_ID 가 살아있으면 생략)
SP_APP_ID=$(databricks service-principals list -p $PROF -o json | jq -r '.[]|select(.displayName=="airag-llm-gw-sp").applicationId')
# 2) 새 OBO 토큰(2년) 발급 → 같은 secret 키(token) 덮어쓰기
databricks secrets put-secret airag_llm_gw token \
  --string-value "$(databricks token-management create-obo-token "$SP_APP_ID" --lifetime-seconds 63072000 --comment "airag-llm-gw rotate" -p $PROF -o json | jq -r .token_value)" -p $PROF
# 3) (반영 보장) 엔드포인트가 새 토큰을 다시 읽도록 ai_gateway 설정 no-op 재적용
#    gw_only.json = §3.2.3 의 "ai_gateway" 블록만 담은 파일
databricks serving-endpoints put-ai-gateway ke-airag-llm-gw --json @gw_only.json -p $PROF

• 토큰 만료 = 게이트웨이 중단 — 만료/무효 토큰은 upstream 403 Invalid access token 을 유발하고, 폴백 조건(429/5XX)이 아니라 그대로 에러가 됩니다(§3.3). 자동 갱신이 없으니 만료 전 (B) 로테이션이 필수입니다(만료 며칠 전 알림·스케줄 잡 권장).
• 반영 보장 — (B)-3 의 put-ai-gateway no-op 재적용은 secret 갱신 후 새 토큰을 확실히 다시 읽게 하는 용도입니다(secret 즉시 반영 여부는 환경별로 다를 수 있음).

3.2.2 Custom serving endpoint (콘솔)

메뉴 위치: workspace 좌측 Serving → Create serving endpoint.

1단계 — 이름: 이름 ke-airag-llm-gw 입력.

2단계 — main 모델 추가: Add served entity → Select served entity → "Select a foundation model" 드롭다운 → External model providers 그룹의 Databricks Model Serving 선택. (Gemini/Claude 는 built-in 목록에 없습니다)

3단계 — Provider configuration: Confirm 후 Entity details 에서 — Databricks API secret = Secret Reference 선택 → {{secrets/airag_llm_gw/token}}(§3.2.1) · Databricks Workspace URL = https://<deployment>.cloud.databricks.com · Task = Chat(llm/v1/chat) · Provider model = databricks-gemini-3-flash · Traffic = 100.

4단계 — backup 모델 추가: Add served entity 로 하나 더, 같은 방식 — Provider model = databricks-claude-sonnet-4-6, Traffic = 0(폴백 전용). Summary 에 두 모델(100% / 0%)이 표시됩니다.

5단계 — AI Gateway: Advanced options → AI Gateway → Enable fallbacks(429/5xx 시 등록 순서 failover) · Enable inference tables(catalog·schema·prefix) · Enable usage tracking → Create.

3.2.3 Custom serving endpoint (CLI)

콘솔(§3.2.2)과 동일 구성을 JSON 으로 만듭니다(같은 secret airag_llm_gw/token 참조).

PROF=<profile> ; HOST=https://<deployment>.cloud.databricks.com
cat > /tmp/gw.json <<JSON
{
  "name": "ke-airag-llm-gw",
  "config": {
    "served_entities": [
      {
        "name": "gemini-flash",
        "external_model": {
          "name": "databricks-gemini-3-flash",
          "provider": "databricks-model-serving",
          "task": "llm/v1/chat",
          "databricks_model_serving_config": {
            "databricks_workspace_url": "$HOST",
            "databricks_api_token": "{{secrets/airag_llm_gw/token}}"
          }
        }
      },
      {
        "name": "sonnet",
        "external_model": {
          "name": "databricks-claude-sonnet-4-6",
          "provider": "databricks-model-serving",
          "task": "llm/v1/chat",
          "databricks_model_serving_config": {
            "databricks_workspace_url": "$HOST",
            "databricks_api_token": "{{secrets/airag_llm_gw/token}}"
          }
        }
      }
    ],
    "traffic_config": {
      "routes": [
        { "served_model_name": "gemini-flash", "traffic_percentage": 100 },
        { "served_model_name": "sonnet",       "traffic_percentage": 0 }
      ]
    }
  },
  "ai_gateway": {
    "fallback_config": { "enabled": true },
    "usage_tracking_config": { "enabled": true },
    "inference_table_config": {
      "enabled": true,
      "catalog_name": "<catalog>",
      "schema_name": "<schema>",
      "table_name_prefix": "ke_airag_llm_gw"
    }
  }
}
JSON
databricks serving-endpoints create --json @/tmp/gw.json -p $PROF

• traffic_percentage 0% entity 는 폴백 전용. 기능만 변경은 databricks serving-endpoints put-ai-gateway <name> --json @gw_only.json (ai_gateway 블록만).
• 에이전트 serving SP 는 이 프록시에 CAN_QUERY 필요 — 모델 로깅 시 resources=[DatabricksServingEndpoint("ke-airag-llm-gw")] 로 자동 부여(§4.2).

 

3.3 폴백 발동 조건

• upstream 의 429(레이트리밋) 또는 5XX(서버 장애) 에서만 발동합니다. 최대 2개 폴백, 등록 순서대로 시도, 첫 성공 시 중단.
• 폴백이 안 되는 케이스: 4xx(400/401/403/404), 타임아웃, DNS/전송 오류("destination host can not be resolved"). 즉 잘못된 모델명·인증 실패는 폴백되지 않고 에러가 그대로 반환됩니다.
• 참고: 애플리케이션 코드 폴백(예: agent.py 의 50x 분기)은 50x 만 커버 → 게이트웨이는 429 까지 넓지만 4xx 는 양쪽 모두 미커버.

 

4. Model Serving 통합 (소스·배포)

custom-model 에이전트가 게이트웨이 프록시를 LLM 으로 호출하면, 폴백·로깅을 게이트웨이에 위임하고 에이전트 코드는 엔드포인트 이름만 바꾸면 됩니다.

 

4.1 에이전트 소스 예제

게이트웨이를 LLM 으로 호출하는 핵심만 발췌입니다. 전체 ResponsesAgent 골격(predict/predict_stream·스트리밍 이벤트·set_model)은 일반 MLflow 에이전트 패턴이라 샌드박스 배포 가이드 부록 A 를 정본으로 참조하세요.

from databricks.sdk import WorkspaceClient

# 엔드포인트 런타임이 자동 주입한 자격으로 인증 — 코드에 토큰 없음.
# 게이트웨이 호출 권한(CAN_QUERY)은 §4.2 의 resources 로 자동 부여됨.
client = WorkspaceClient().serving_endpoints.get_open_ai_client()

# ★ 폴백 핵심: LLM 대상을 AI Gateway 프록시 "이름"으로 지정하는 것이 전부.
#   429/5XX 시 Gemini→Sonnet 전환은 게이트웨이가 처리(§3.3) → 에이전트엔 폴백/재시도 코드 없음.
stream = client.chat.completions.create(
    model="ke-airag-llm-gw",       # 게이트웨이 엔드포인트 = 폴백 묶음(Gemini 100% → Sonnet 0%)
    messages=messages, stream=True,
    max_tokens=2048)               # Gemini reasoning 토큰 소비 대비(빈 응답 방지)

폴백 모델(Gemini↔Sonnet)이 OpenAI chat completions 호환이라 에이전트에 폴백 코드 없이 model= 만 게이트웨이 이름으로 두면 됩니다(폴백은 게이트웨이가 §3.3 규칙대로 처리). 스트리밍(SSE) 은 프록시를 그대로 통과함을 확인했습니다. Gemini 는 reasoning 토큰을 소비하므로 max_tokens 를 충분히(예: ≥ 512) 둡니다.

 

4.2 로깅·배포 절차

import mlflow
from mlflow.models.resources import DatabricksServingEndpoint
from databricks import agents

MODEL = "<catalog>.<schema>.css_cmarket_rag_agent"
mlflow.set_registry_uri("databricks-uc")
exp = mlflow.set_experiment("/Users/<you>@example.com/css_cmarket_rag_agent_exp")
with mlflow.start_run():
    logged = mlflow.pyfunc.log_model(
        name="agent", python_model="agent.py",
        input_example={"input": [{"role": "user", "content": "화물 운임 변동 이유는?"}]},
        pip_requirements=["mlflow", "databricks-sdk", "openai"],
        # ★ 게이트웨이 호출 권한: 이 resource 선언이 에이전트 serving SP 에 게이트웨이 CAN_QUERY 를 자동 부여.
        resources=[DatabricksServingEndpoint(endpoint_name="ke-airag-llm-gw")])
mv = mlflow.register_model(logged.model_uri, MODEL)
agents.deploy(MODEL, int(mv.version),
              endpoint_name="css_cmarket_rag_agent", scale_to_zero=True,
              environment_vars={"MLFLOW_EXPERIMENT_ID": exp.experiment_id})

절차·전제: 1. 게이트웨이 프록시가 먼저 READY 여야 합니다(§3.2). 2. resources=[DatabricksServingEndpoint("ke-airag-llm-gw")] 가 에이전트 serving SP 에 게이트웨이 CAN_QUERY 를 자동 부여합니다. 주의: 게이트웨이를 삭제·재생성하면(endpoint id 가 바뀜) 이 grant 가 사라져 에이전트 호출이 403 이 됩니다 → 게이트웨이 재생성 후 에이전트 재배포(또는 새 엔드포인트에 CAN_QUERY 재부여)가 필요합니다. 3. 배포는 OAuth 사용자 계정(CLI 프로필) 또는 서버리스 노트북에서 실행 — 별도 토큰 불필요(§3.2.1 노트). 로컬 실행 시 venv 는 Python 3.10 권장(3.14 는 일부 휠 이슈). 4. agents.deploy 후 엔드포인트 갱신 ~10–15분. READY 후 앱의 serving_endpoint_name 을 (재)지정. 5. 검증: 엔드포인트 invoke → 200 + 정상 응답, 이후 inference table 에 served_model=gemini-3-flash-preview 적재(§5.1). 6. 샌드박스 도메인별(catalog·experiment·endpoint) 전체 절차 = 샌드박스 배포 가이드 부록 A.

 

5. 모니터링 (Inference Table · Usage Tracking)

게이트웨이 호출 결과는 두 경로로 관찰합니다 — Inference Table(페이로드 원문 로깅, §5.1)과 Usage Tracking(토큰/요청 집계 시스템 테이블, §5.2). 폴백이 실제로 발동했는지·어느 모델이 응답했는지는 Inference Table 로, 비용·토큰 사용량 집계는 Usage Tracking 으로 봅니다.

본 프로젝트 운영 결정: A항공 RAG 는 요청/응답에 개인정보(PII)가 포함될 수 있어 Inference Table 을 비활성화합니다(§5.1). 따라서 실제 운영 관측은 원문을 남기지 않는 Usage Tracking(§5.2) 중심으로 합니다.

 

5.1 Inference Table

비활성화 (PII): 본 프로젝트에서는 Inference Table 을 켜지 않습니다. 요청/응답 원문이 UC Delta 테이블에 평문으로 영구 적재되는데, A항공 RAG 의 프롬프트·완성에는 개인정보(PII)가 포함될 수 있기 때문입니다. 토큰·요청 집계가 필요하면 원문을 저장하지 않는 Usage Tracking(§5.2) 으로 대체합니다. 아래 설정·스키마·예시는 기능 이해 및 향후 마스킹·접근통제·보존정책을 갖춘 뒤 선택적으로 도입할 때를 위한 참고용입니다.

설정

ai_gateway.inference_table_config 로 켜며, 켜는 즉시 UC 에 빈 테이블이 생성되고 이후 호출이 비동기로 적재됩니다.

필드	의미
enabled	활성화 여부
catalog_name · schema_name	테이블이 생성될 UC 위치 (쓰기 권한 필요)
table_name_prefix	테이블명 접두사 → 실제 테이블 = <prefix>_payload

적재 지연: 페이로드는 비동기 배치 적재 라 즉시 보이지 않습니다 — 본 환경에서 약 12분, 공식 문서상 최대 ~1시간. 적재 전 count(*) 가 0 이어도 정상입니다. 저장 한계: 1 MiB 초과 페이로드는 로깅되지 않습니다. 요청/응답 원문(프롬프트·완성) 이 그대로 저장되므로 PII·민감정보가 포함될 수 있어 접근 통제·보존 정책을 적용하세요.

저장 내용 (스키마·컬럼)

테이블 <prefix>_payload (Delta, UC)의 컬럼:

컬럼	내용
databricks_request_id	요청 고유 ID (trace·디버깅 연결 키)
client_request_id	클라이언트가 보낸 식별자(없으면 null)
request_date	요청 날짜(파티션 키)
request_time	요청 타임스탬프
status_code	HTTP 상태 코드 (200 / 4xx / 5xx)
sampling_fraction	로깅 샘플링 비율(1.0 = 전량)
execution_duration_ms	처리 소요 시간(ms)
request	요청 페이로드 원문(JSON 문자열 — messages/input 등)
response	응답 페이로드 원문(JSON 문자열 — choices, model 등)
served_entity_id	실제로 응답한 served entity id (폴백 발생 시 어느 모델이 응답했는지 식별)
requester	호출 주체(user/SP)
logging_error_codes	로깅 단계 오류 코드

폴백 모니터링 활용: served_entity_id 와 response 안의 "model" 값으로 어느 모델이 응답했는지를 추적합니다. 평소 main(예: gemini-3-flash-preview)이 찍히다가 backup(Sonnet)으로 바뀌면 폴백이 발동한 것이며, status_code 와 함께 보면 429/5XX → 폴백 전환을 사후 분석할 수 있습니다.

조회·저장 예시

-- 최근 호출 + 실제 서빙 모델 (게이트웨이 프록시)
SELECT request_time, status_code, served_entity_id,
       regexp_extract(response, '"model":"([^"]+)"', 1) AS served_model,
       execution_duration_ms
FROM <catalog>.<schema>.ke_airag_llm_gw_payload
ORDER BY request_time DESC
LIMIT 20;

확인 결과(서울 리전, dbc-xxxxxxxx-xxxx): RAG 에이전트 호출 3건이 프록시를 통과해 모두 status_code=200, served_model=gemini-3-flash-preview(= main 정상), 에이전트 inference table(css_cmarket_rag_agent_payload)의 호출과 타임스탬프가 1:1 대응 했습니다.

저장 예시 (실제 1건, ke_airag_llm_gw_payload):

컬럼	값
request_time	2026-06-19T08:56:53.518Z
status_code	200
execution_duration_ms	9912
served_entity_id	0d866c4139494b0bacbf04fa2619150d (= gemini-flash)
requester	b160a8cb-… (에이전트 serving SP)
request	{"messages":[{"role":"user","content":"위험물 화물 운송 시 주의사항은?"}],"max_tokens":2048,"stream":true}
response	{"object":"chat.completion.chunk","model":"gemini-3-flash-preview","choices":[{"index":0,"message":{"role":"assistant","content":"위험물(Dangerous Goods) 화물 운송은 작은 실수가 대형 사고…"}}]}

request·response 에 프롬프트·완성 원문이 그대로 저장됩니다(스트리밍 호출이라 stream:true·chat.completion.chunk 형태). response.model = gemini-3-flash-preview 로 main(Gemini)이 응답했음을, served_entity_id 로 어느 entity 가 처리했는지 식별합니다 — 폴백이 발동했다면 여기에 backup(Sonnet) entity·모델이 찍힙니다.

 

5.2 Usage Tracking (시스템 테이블)

페이로드 원문 없이 토큰/요청 집계 만 필요하면 usage tracking 으로 충분합니다.

시스템 테이블	내용 (공식 카탈로그 코멘트 기준)
system.serving.endpoint_usage	Model Serving 의 요청별 사용량을 기록합니다 — served entity 별로 LLM 토큰이 얼마나 전송됐는지 귀속하는 데 사용하며, served_entity_id 를 키로 served_entities 와 조인해 엔티티 정보를 조회합니다.
system.serving.served_entities	Databricks Model Serving 으로 서빙된 모든 엔티티와 config 버전별 구성을 기록합니다.

두 테이블은 served_entity_id 로 조인됩니다 — endpoint_usage(요청별 사용량) 한 행의 served_entity_id 를 served_entities(엔드포인트↔모델 메타)에서 찾으면 어느 엔드포인트의 어느 모델이 처리했는지 알 수 있습니다.

(1) endpoint_usage — 요청별 토큰/상태 집계

컬럼	내용
workspace_id	엔드포인트가 존재하는 워크스페이스 ID
account_id	워크스페이스의 Databricks 계정 ID
client_request_id	요청 본문에 지정 가능한 클라이언트 제공 식별자(없으면 null)
databricks_request_id	Databricks 가 모든 서빙 요청에 부여하는 요청 ID
requester	호출 권한 주체(user/SP 의 이름·이메일)
status_code	모델이 반환한 HTTP 상태 코드
request_time	요청 수신 타임스탬프
input_token_count	입력 토큰 수
output_token_count	출력 토큰 수
input_character_count	입력 문자열(프롬프트) 문자 수
output_character_count	출력 문자열(응답) 문자 수
usage_context	엔드 유저·호출 애플리케이션 식별자를 담는 사용자 제공 map(미지정 시 {})
request_streaming	스트림 모드 여부
served_entity_id	served_entities 와 조인해 엔드포인트·엔티티 정보를 조회하는 키

저장 예시 (게이트웨이 ke-airag-llm-gw 경유):

request_time	requester	status_code	input_token_count	output_token_count	request_streaming	served_entity_id
2026-06-19T17:14:26.277Z	8b3ae289-…(SP)	200	31	32	true	d64145ab…
2026-06-19T17:13:21.463Z	8b3ae289-…(SP)	200	1	9	false	d64145ab…
2026-06-19T17:11:55.654Z	8b3ae289-…(SP)	200	21	72	true	d64145ab…

(2) served_entities — served entity 메타(엔드포인트↔모델 매핑)

컬럼	내용
served_entity_id	served entity 고유 ID (endpoint_usage 와의 조인 키)
account_id	계정 ID
workspace_id	워크스페이스 ID
created_by	생성 주체(user/SP/group 이름)
endpoint_name	서빙 엔드포인트 이름
endpoint_id	서빙 엔드포인트 고유 ID
served_entity_name	served entity 이름(사용자 지정명)
entity_type	엔티티 타입 (EXTERNAL_MODEL/FOUNDATION_MODEL/CUSTOM_MODEL/FEATURE_SPEC)
entity_name	엔티티 실제 이름(예: UC 모델명). served_entity_name 과 다름
entity_version	served entity 버전
endpoint_config_version	엔드포인트 구성 버전
task	태스크 타입 (llm/v1/chat/llm/v1/completions/llm/v1/embeddings)
external_model_config	external model 구성 (예: {provider: ...})
foundation_model_config	foundation model 구성 (min/max provisioned throughput)
custom_model_config	custom model 구성 (min/max concurrency·compute_type)
feature_spec_config	feature spec 구성 (min/max concurrency·compute_type)
change_time	served entity 변경 타임스탬프
endpoint_delete_time	엔티티(엔드포인트) 삭제 타임스탬프

저장 예시 (위 served_entity_id 가 가리키는 엔티티):

served_entity_id	endpoint_name	entity_type	entity_name	endpoint_config_version	change_time
d64145ab…	ke-airag-llm-gw	EXTERNAL_MODEL	databricks-gemini-3-flash	1	2026-06-19T15:09:04.263Z
ce85d55b…	ke-airag-llm-gw	EXTERNAL_MODEL	databricks-claude-sonnet-4-6	1	2026-06-19T15:09:04.264Z

조인 해석: endpoint_usage 의 served_entity_id=d64145ab… 를 served_entities 에서 찾으면 ke-airag-llm-gw 의 databricks-gemini-3-flash(EXTERNAL_MODEL) — 즉 위 토큰 집계는 게이트웨이가 main(Gemini)으로 응답한 호출임이 확인됩니다. 폴백이 발동했다면 served_entity_id 가 backup(Sonnet, ce85d55b…) 행을 가리킵니다. databricks_request_id 로는 inference table(§5.1 페이로드 원문)과 join 해 어떤 요청이 토큰을 얼마나 썼는지 연결합니다. output_token_count 에는 Gemini reasoning 토큰이 포함되어 짧은 답변도 출력 토큰이 크게 잡힐 수 있습니다.

 

6. 참고 자료

• AI Gateway 엔드포인트 구성
• Inference tables (AI Gateway)
• Features with limited regional availability

 

부록 A. 게이트웨이 모델 선택 가이드 (tools·reasoning·등급)

 

A-1 A항공 Agentic RAG 기준 게이트웨이 구성

A항공 Agentic RAG(agentic_rag_0619)는 tools + reasoning_effort 를 함께 사용하므로, AI Gateway 는 이 조합을 통과하는 모델로 구성해야 합니다 — main = databricks-gemini-3-flash, backup = databricks-gpt-5-mini. 두 모델 모두 chat/completions 에서 tools+reasoning_effort 동시 호출을 통과하고, gpt-5-mini 는 flash 와 같은 중간(workhorse) 등급 + 다른 provider(OpenAI) 라 장애 독립성도 확보됩니다. 모델 등급 대응은 A-2, tools·reasoning 지원 근거는 A-3 을 참조하세요.

 

A-2 3개사 등급 대응

벤더 공식 1:1 등가표는 없으며, 네이밍·포지션 기준의 대응입니다.

등급	Claude (Anthropic)	GPT (OpenAI)	Gemini (Google)
최상위 (flagship)	opus	gpt-5 / gpt-5-4	gemini-3-pro
중간 (workhorse)	sonnet	gpt-5-mini / gpt-5-4-mini	gemini-3-flash
경량 (light)	haiku	gpt-5-nano / gpt-5-4-nano	gemini-3-flash-lite

→ gemini-3-flash 의 동급 GPT = gpt-5-mini (중간 workhorse 티어).

 

A-3 tools·reasoning 지원 매트릭스

세 컬럼의 의미:

• tools (function calling) — 모델이 "이 함수를 이런 인자로 호출하라"는 구조화된 요청(tool_calls)을 반환하는 기능. ReAct·검색 도구 호출에 필수.
• reasoning_effort — OpenAI식 추론 강도 파라미터(low/medium/high). 답을 내기 전 사고(reasoning)에 쓰는 자원을 조절.
• tools + reasoning_effort — 위 둘을 한 요청에 동시 전달(/v1/chat/completions). A항공 Agentic RAG 가 실제로 쓰는 방식이라 폴백 모델도 이 조합을 통과해야 합니다.

Claude 와 reasoning: Claude 는 추론 자체는 extended thinking 으로 지원하지만, OpenAI식 reasoning_effort 파라미터는 받지 않습니다(400). 따라서 reasoning_effort 기반 게이트웨이 구성과는 호환되지 않습니다 — Claude 로 추론을 쓰려면 별도 thinking 파라미터를 써야 합니다.

서울 리전 chat/completions 기준 실측. 등급보다 세대·계열이 지원 여부를 가릅니다.

계열	모델	등급	tools	reasoning_effort	tools+reasoning
Claude 4.x	claude-opus-4-8	flagship	✅	❌	❌
	claude-sonnet-4-6	중간	✅	❌	❌
	claude-haiku-4-5	경량	✅	❌	❌
GPT-5.0	gpt-5	flagship	✅	✅	✅
	gpt-5-mini	중간	✅	✅	✅
	gpt-5-nano	경량	✅	✅	✅
GPT-5.4	gpt-5-4	flagship	✅	✅	❌
	gpt-5-4-mini	중간	✅	✅	❌
	gpt-5-4-nano	경량	✅	✅	❌
GPT-OSS	gpt-oss-120b / 20b	대형/소형	✅	✅	✅
Gemini 3.x	gemini-3-pro	flagship	✅	✅	✅
	gemini-3-flash	중간	✅	✅	✅
	gemini-3-1-flash-lite	경량	✅	✅	✅
Gemini 2.5	gemini-2-5-pro / flash	flagship/중간	✅	❌	❌

패턴 요약:

• tools: 전 모델 지원(등급·계열 무관).
• reasoning_effort: GPT-5/5.4/OSS·Gemini 3.x ✅ / Claude 전체·Gemini 2.5 ❌.
• tools+reasoning(동시, chat/completions): GPT-5.0·OSS·Gemini 3.x ✅ / GPT-5.4(→responses 전용)·Claude·Gemini 2.5 ❌.
• 등급(pro/flash/mini/nano)은 지원 여부에 영향 없음 — 같은 세대 안에선 동일.

폴백 적격(tools+reasoning 동시 필요): GPT-5.0 계열·GPT-OSS·Gemini 3.x. → flash main 의 동급·독립 provider·적격 조합을 모두 만족하는 gpt-5-mini 가 최적.

 

📚 시리즈 — Databricks LLMOps

• ① AI Gateway — LLM 폴백·게이트웨이 프록시 — 현재 글
• ② Prompt Registry — 프롬프트 버전·alias 관리
• ③ MLflow Tracing — LangGraph 관측·PII 마스킹