AI Providers & Bindings — Admin UI

이 문서는 운영자/관리자가 GenD에 사용할 LLM(대규모 언어 모델) 제공자를 등록하고, 챗·브리핑·온톨로지 매핑 같은 기능별로 어떤 모델을 쓸지 지정할 때 사용합니다.

무엇을 할 수 있나요

GenD의 AI 기능(채팅, 브리핑, 문서 처리 등)이 외부 LLM API를 호출하려면, 운영자가 먼저 AI Provider(어떤 API를 쓸지)를 등록하고 AI Binding(어떤 기능에 어떤 provider를 쓸지)을 지정해야 합니다. 본 화면에서 두 작업을 모두 GUI로 처리할 수 있고, 등록 즉시 Healthcheck로 연결을 검증할 수 있습니다.

그림: AI Providers 관리 화면 — provider 1건 등록된 상태.

누가 사용할 수 있나요

역할	접근 권한
admin realm role 보유 사용자	모든 워크스페이스의 provider/binding 관리 가능
워크스페이스 멤버 (Keycloak group /tenants/{slug})	본 화면 접근 불가 (자기 워크스페이스 override는 워크스페이스 AI 설정 화면 사용)
그 외 사용자	403 Forbidden

접근 권한 부여 절차

• 전사 운영자로 지정하려면: Keycloak Console → Users → 대상 사용자 → Role Mapping → Realm Roles → admin 추가
• 특정 워크스페이스만 다루게 하려면: 본 화면 대신 워크스페이스 AI 설정 가이드 참고 (Keycloak Console → Groups → /tenants/{slug} → Members → 사용자 추가)

화면 둘러보기

진입 경로

메뉴	라우트
⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 제공자	/admin/llm-providers
⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 바인딩	/admin/llm-bindings

사이드바 하단 ⚙ 관리 콘솔 드릴인의 AI & MCP 플랫폼 그룹에 위치합니다. (참고: 공용 수집기 (관리형) 메뉴는 데이터플레인 설정 그룹입니다.)

AI Providers 화면

컬럼	설명
Name	provider 식별 이름 (중복 불가)
Kind	LLM / VLM / Embedding 배지
Endpoint	호출 base URL (예: https://api.genon.ai/v1)
Default Model	별도 override 가 없을 때 사용할 기본 모델
Enabled	사용 여부 토글
Health	up / down / untested 배지 (마지막 헬스체크 결과)
Cost /1M	1M 토큰당 입력/출력 비용 (사용량 화면에서 사용)
Actions	🩺 Healthcheck · 🗑 Delete

오른쪽 위 + Add Provider 버튼으로 신규 등록 다이얼로그가 열립니다.

Add Provider 다이얼로그

그림: Add Provider 다이얼로그 — Name / Kind / API Format / Endpoint / Vault Secret Path / Default Model 등 필드.

필드	입력 예시 / 설명
Name (필수)	GenON Qwen 3.5 397B — UI 전체에서 보이는 식별자
Kind	LLM / VLM / Embedding 중 하나 선택
API Format	OpenAI-compatible / Anthropic / Vertex / Bedrock
Endpoint (필수)	https://api.genon.ai/v1 — https 만 허용
Vault Secret Path (필수)	미리 vault kv put 으로 api_key 저장한 경로
Default Model (필수)	qwen/qwen3.5-397b-a17b-fp8
Max tokens / Timeout	응답 최대 토큰, 호출 타임아웃 (초)
Cost in/out $/1M	1M 토큰당 비용 (USD)

저장 시 중복 이름이면 409 에러가 토스트로 표시됩니다.

AI Bindings 화면

그림: AI Bindings 매트릭스 — 행은 use_case, 열은 Global + 워크스페이스.

행은 7개 use_case (chat, agent, briefing, ontology_mapper, document_processing, vlm_caption, embedding), 열은 Global(기본값) 과 등록된 워크스페이스입니다. 셀의 — 표시는 미설정을 의미하고, 호출 시 워크스페이스 → Global → 환경변수 순으로 폴백합니다.

오른쪽 위 + Add Binding 으로 셀에 provider 를 매핑합니다. 같은 (use_case, workspace) 조합은 1개만 등록할 수 있어, 변경하려면 기존 행을 🗑 로 삭제 후 재등록합니다.

단계별 사용법

시나리오 1 — 처음 LLM provider 등록하기

가장 흔한 시나리오입니다. GenON Qwen 키를 받아 Global default 로 채팅에 연결합니다.

1. 터미널에서 Vault 에 API 키를 먼저 저장하세요.

   vault kv put secret/gend/llm-providers/genon-prod api_key=sk-svp-xxxx

2. ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 제공자 진입 → 우측 위 + Add Provider 클릭
3. 다이얼로그에 다음과 같이 입력하세요.
   • Name: GenON Qwen 3.5 397B
   • Kind: LLM, API Format: OpenAI-compatible
   • Endpoint: https://api.genon.ai/v1
   • Vault Secret Path: secret/gend/llm-providers/genon-prod
   • Default Model: qwen/qwen3.5-397b-a17b-fp8
   • Cost in: 0.50, Cost out: 1.50
4. Save 클릭 → 테이블에 새 row 가 추가됩니다.
5. 등록된 행의 🩺 Healthcheck 버튼을 눌러 연결을 검증하세요.

그림: Healthcheck 클릭 직후 표시되는 토스트 — status, latency, 응답 detail.

토스트에 status: up 과 응답 시간이 보이면 정상입니다. down 이면 Vault 키 경로 또는 endpoint URL 을 다시 확인하세요.

시나리오 2 — 채팅 기능을 등록한 provider 에 연결

provider 가 등록되어 있어도 binding 이 없으면 채팅 기능은 동작하지 않습니다.

1. ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 바인딩 진입
2. + Add Binding 클릭
3. 다이얼로그에서 다음과 같이 입력하세요.
   • Use Case: chat
   • Workspace: Global (default)
   • Provider: GenON Qwen 3.5 397B
4. Save → 매트릭스의 chat / Global 셀에 provider 이름이 표시됩니다.
5. 동일한 절차로 briefing, ontology_mapper 등 다른 use_case 도 매핑하세요.

시나리오 3 — 특정 워크스페이스만 다른 모델로 override

finance-invest 워크스페이스의 briefing 만 별도 provider 를 쓰고 싶을 때:

1. 추가로 사용할 provider 가 이미 등록·헬스체크 통과되어 있는지 확인하세요.
2. ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 바인딩 → + Add Binding
3. Use Case: briefing, Workspace: finance-invest, Provider: 해당 provider 선택
4. Save → 매트릭스에서 briefing / finance-invest 셀이 채워집니다.

참고: VLM (이미지 캡션) 이나 Anthropic 같은 별도 모델을 추가하려면 Vault 에 새 키를 저장한 뒤 동일하게 Add Provider 로 등록하면 됩니다. 본 가이드는 LLM 기본 예시만 다룹니다.

API 직접 호출 (선택)

UI 없이 스크립트로 처리하고 싶을 때는 다음 두 호출만으로 충분합니다.

# 1) Provider 등록
curl -X POST https://gend.genon.ai/api/v1/admin/llm-providers \
  -H "Authorization: Bearer $GEND_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GenON Qwen 3.5 397B",
    "kind": "llm",
    "api_format": "openai_compat",
    "endpoint": "https://api.genon.ai/v1",
    "vault_path": "secret/gend/llm-providers/genon-prod",
    "default_model": "qwen/qwen3.5-397b-a17b-fp8"
  }'

# 2) 어떤 provider 가 실제로 적용되는지 검증
curl "https://gend.genon.ai/api/v1/llm-bindings/effective?use_case=briefing&workspace_slug=finance-invest" \
  -H "Authorization: Bearer $GEND_ADMIN_JWT"

자주 묻는 질문 / 문제 해결

Q. Healthcheck 결과가 down 으로만 나옵니다. A. (1) Vault 경로에 api_key property 가 정확히 저장됐는지 vault kv get <path> 로 확인하세요. (2) Endpoint URL 끝에 /v1 같은 경로가 빠지지 않았는지 확인하세요. (3) Vault 자체가 sealed/down 상태면 모든 provider 가 동시에 down 으로 표시됩니다.

Q. Add Binding 시 409 에러가 납니다. A. 같은 (use_case, workspace) 조합에 이미 binding 이 등록돼 있습니다. 매트릭스에서 해당 셀의 기존 binding 을 🗑 로 삭제한 뒤 다시 등록하세요.

Q. provider 를 삭제하면 그 provider 를 쓰던 binding 은 어떻게 되나요? A. 해당 binding 도 함께 제거됩니다. 삭제 전 매트릭스에서 어떤 셀에 영향을 주는지 먼저 확인하세요.

Q. 워크스페이스 멤버에게 자기 워크스페이스 cell 만 바꾸게 하려면? A. 본 화면은 admin 전용입니다. 워크스페이스 멤버는 별도의 "워크스페이스 AI 설정" 화면 (/workspace/{slug}/ai-settings) 에서 자기 워크스페이스 컬럼만 수정할 수 있습니다.

Q. 매트릭스 셀이 비어 있어도 채팅이 동작하나요? A. Global cell 이 채워져 있으면 폴백으로 동작합니다. Global 도 비어 있으면 환경변수(GEND_LLM_*) 폴백이 시도되고, 그것마저 없으면 503 에러가 발생합니다.