LLM Providers — 외부 모델 등록

이 문서는 운영자/관리자가 GenD 에서 사용할 외부 LLM 엔드포인트(예: GenON Qwen, 사내 vLLM, OpenAI 호환 API 등)를 등록·관리할 때 사용합니다. AI Chat, NL2SQL, RAG 등 모든 LLM 기반 기능은 여기서 등록한 provider 를 통해 호출됩니다.

누가 사용할 수 있나요

사용자	가능한 작업
`admin` realm role 보유	모든 provider 등록·수정·삭제·healthcheck
워크스페이스 멤버	본인 워크스페이스에서 사용할 provider 선택 (별도 Workspace AI Settings 참조)
그 외	403 — 본 페이지 접근 불가

Provider 등록은 전사 공통 자산이므로 admin role 이 필요합니다. 워크스페이스별 모델 정책은 다른 페이지에서 다룹니다.

접근 권한 부여 절차

Keycloak Console 접속 → gend realm 선택
Users → 해당 사용자 → Role mapping 탭
Assign role → admin 선택 → Assign

무엇을 할 수 있나요

운영자는 이 페이지에서 다음 작업을 수행합니다.

외부 LLM 엔드포인트를 GenD 에 등록 (이름·URL·기본 모델·비용 단가)
API 키는 Vault 에 저장하고 경로만 DB 에 기록 (평문 저장 X)
엔드포인트가 정상인지 healthcheck 한 번에 확인
모델 화이트리스트로 허용 모델 제한
일시 비활성화 / 영구 삭제

AI Providers 관리 화면

그림: ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 제공자 페이지. 등록된 provider 가 표 형태로 표시됩니다.

화면 둘러보기

사이드바 하단 ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 제공자 클릭 시 보이는 항목입니다.

컬럼 / 버튼	의미
Name	사람이 알아보기 쉬운 식별자 (예: `GenON Qwen 3.5 397B`)
Kind	`llm` / `vlm` / `embedding` — 용도 구분
Endpoint	호출 base URL
Default Model	별도 지정 없을 때 사용할 모델명
Enabled	토글 — off 시 호출 차단
Health	마지막 healthcheck 결과 (`up` / `down` / 미실행)
Cost	1M 토큰당 입력/출력 단가 (USD)
Test 버튼	endpoint 실시간 확인 (과금 없음)
Edit / Delete	수정 / 삭제 (binding 있으면 삭제 차단)
+ Add Provider	우상단 — 신규 등록 다이얼로그

단계별 사용법

시나리오 1 — GenON Qwen 신규 등록

가장 일반적인 작업입니다. 사내 GenON 엔드포인트를 처음 등록한다고 가정합니다.

Vault 에 API 키 저장 — 운영팀이 발급한 키를 Vault 에 먼저 넣어둡니다.
```
vault kv put secret/gend/llm-providers/genon-prod api_key=sk-svp-xxxxx
```
⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 제공자 진입 → 우상단 + Add Provider 클릭

그림: Add Provider 다이얼로그 — Name / Kind / Endpoint / Vault 경로 / Default Model 입력.

다음 값으로 입력하세요.

필드	값
Name	`GenON Qwen 3.5 397B`
Kind	`llm`
Endpoint	`https://api.genon.ai/v1`
Vault Secret Path	`secret/gend/llm-providers/genon-prod`
Default Model	`qwen/qwen3.5-397b-a17b-fp8`
Cost (input / output, 1M USD)	`0.50` / `1.50`
Enabled	on

Save 클릭 → 표에 새 행이 추가됩니다.
새 행의 Test 버튼 클릭 → 우하단 토스트로 결과 확인.

그림: Healthcheck 성공 시 latency(ms) 와 함께 up 표시.

시나리오 2 — 허용 모델 추가하기

기존 provider 가 새 모델을 지원하기 시작했을 때 화이트리스트를 늘립니다.

표에서 해당 provider 행의 Edit 클릭
Model Whitelist 입력란에 모델명 추가 (콤마 구분)
- 예: qwen/qwen3.5-397b-a17b-fp8, qwen/qwen3.5-14b
Save 클릭

화이트리스트 밖 모델로 호출하면 자동으로 거부됩니다.

시나리오 3 — 잠시 끄기 / 삭제하기

잠시 끄기 — 표의 Enabled 토글을 off. 설정은 유지되며 호출만 차단됩니다.
영구 삭제 — Delete 버튼. 단, 이 provider 를 사용하는 워크스페이스 바인딩이 있으면 409 에러로 막힙니다. 먼저 Bindings 페이지에서 연결을 해제하세요.

API 직접 호출 (선택)

UI 대신 스크립트나 CI 에서 등록할 때 사용합니다.

TOKEN=$(cat ~/.gend/token.json | jq -r .access_token)

curl -sS -X POST "https://gend.genon.ai/api/v1/admin/llm-providers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GenON Qwen 3.5 397B",
    "kind": "llm",
    "endpoint": "https://api.genon.ai/v1",
    "vault_secret_path": "secret/gend/llm-providers/genon-prod",
    "default_model": "qwen/qwen3.5-397b-a17b-fp8",
    "model_whitelist": ["qwen/qwen3.5-397b-a17b-fp8"],
    "cost_per_1m_input_tokens_usd": 0.50,
    "cost_per_1m_output_tokens_usd": 1.50,
    "enabled": true
  }'

성공 시 201 과 함께 provider id 가 반환됩니다.

Healthcheck 만 실행하려면:

PROVIDER_ID=<위에서 받은 id>
curl -sS -X POST \
  "https://gend.genon.ai/api/v1/admin/llm-providers/$PROVIDER_ID/test" \
  -H "Authorization: Bearer $TOKEN"

참고: VLM(이미지 입력 모델) 도 동일한 절차로 등록할 수 있습니다 (kind=vlm). 다만 별도 Vault 키와 endpoint 가 필요하니 본 가이드는 LLM 기본 예시만 다룹니다.

자주 묻는 질문 / 문제 해결

Q1. Healthcheck 가 down 으로 나옵니다. A. 다음을 순서대로 확인하세요.

Endpoint URL 이 /v1 까지 정확한지 (예: https://api.genon.ai/v1)
Vault 경로에 api_key 키가 있는지 — vault kv get secret/gend/llm-providers/genon-prod
AKS 노드에서 외부 호출이 막혀있지 않은지 (방화벽 / egress NetworkPolicy)

Q2. Provider 삭제가 안 됩니다 (409). A. 워크스페이스 바인딩이 남아있다는 뜻입니다. Bindings 페이지에서 use-case 연결을 먼저 해제하거나, 우선 Enabled 토글만 off 로 두세요.

Q3. 화이트리스트에 없는 모델로 호출하면 어떻게 되나요? A. API 가 403 으로 거부합니다. 사용자는 "허용되지 않은 모델" 메시지를 봅니다. 일시 허용이 필요하면 화이트리스트에 추가 후 저장하세요.

Q4. API 키를 바꿔야 합니다. A. Vault 의 값만 갱신하면 됩니다. GenD 는 다음 호출부터 새 키를 자동으로 읽습니다 (Vault 경로는 동일).

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

Q5. 등록한 provider 가 AI Chat 에 안 보입니다. A. 워크스페이스 단위로 별도 활성화가 필요합니다. Workspace AI Settings 페이지에서 해당 워크스페이스에 provider 를 바인딩하세요.

누가 사용할 수 있나요​

접근 권한 부여 절차​

무엇을 할 수 있나요​

화면 둘러보기​

단계별 사용법​

시나리오 1 — GenON Qwen 신규 등록​

시나리오 2 — 허용 모델 추가하기​

시나리오 3 — 잠시 끄기 / 삭제하기​

API 직접 호출 (선택)​

자주 묻는 질문 / 문제 해결​

관련 문서​