LLM Use-case 바인딩

이 문서는 운영자/관리자가 "어떤 기능(예: AI 챗, 브리핑, 온톨로지 매핑)이 어떤 LLM provider 를 쓰도록 할지" 매핑을 관리할 때 사용합니다. 매핑은 워크스페이스 단위로 따로 줄 수도 있고, 전사 기본값(Global) 으로 한 번만 줄 수도 있습니다.

무엇을 할 수 있나요

GenD 의 LLM 호출 사이트(채팅, 에이전트, 브리핑, 온톨로지 매퍼 등)는 코드에 provider 가 하드코딩되어 있지 않습니다. 운영자가 AI Bindings 매트릭스 한 화면에서 "이 use-case 는 이 provider 로" 라고 지정해두면, 백엔드가 호출 시점에 자동으로 적절한 provider 를 골라 호출합니다.

워크스페이스마다 다른 provider 를 쓰고 싶다면 워크스페이스 셀에 따로 지정만 하면 됩니다. 따로 지정하지 않은 워크스페이스는 자동으로 Global 기본값을 사용합니다.

그림: ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 바인딩 매트릭스 — 행은 use-case, 열은 Global + 등록된 워크스페이스.

누가 사용할 수 있나요

사용자 유형	접근 범위
admin realm role 보유자	모든 워크스페이스의 바인딩 조회/생성/수정/삭제
일반 사용자	본 화면 접근 불가 (403) — 워크스페이스 단위 자율 설정은 llm-workspace-settings.md 참조

admin 권한이 없으면 /admin/llm-bindings 페이지 자체가 보이지 않습니다.

접근 권한 부여 절차

운영자에게 본 화면 권한을 주려면 다음 중 하나를 적용하세요.

1. 전사 admin 권한: Keycloak Console → Users → 대상 사용자 → Role Mappings → admin realm role 부여.
2. 특정 워크스페이스 멤버 등록 (워크스페이스 단위 설정만 필요한 경우): Keycloak Console → Groups → /tenants/{slug} → Members → 사용자 추가. 단, 본 화면(전사 매트릭스)은 여전히 admin 만 접근 가능합니다.

부여 후 사용자는 한 번 로그아웃 → 재로그인 해야 새 토큰이 발급됩니다.

화면 둘러보기

영역	설명
행 (use-case)	chat, agent, briefing, ontology_mapper, document_processing, vlm_caption, embedding 7 종
열 (workspace)	가장 왼쪽 Global + 등록된 워크스페이스
셀	현재 매핑된 provider 이름. 비어 있으면 상위 tier(Global → env) 로 fall-through
+ 버튼	비어 있는 셀에서 신규 바인딩 추가
편집 아이콘	기존 바인딩의 provider/model/max_tokens 변경
삭제 아이콘	셀 비우기 (상위 tier 로 위임)

호출 시점에 GenD 는 위에서 아래 순서로 provider 를 찾습니다.

1. 호출자가 직접 넘긴 override (예: 파이프라인 설정)
2. 현재 워크스페이스의 셀
3. Global 셀
4. 환경변수 fallback

단계별 사용법

시나리오 1 — 전사 기본 LLM 지정

처음 도입 시 가장 먼저 해야 할 작업입니다. 모든 use-case 에 대해 Global 열 셀을 채워 두세요. 그래야 워크스페이스 별도 설정이 없어도 모든 사용자가 AI 기능을 쓸 수 있습니다.

1. /admin 메뉴 → AI Bindings 클릭.
2. chat 행 × Global 열 빈 셀의 + 클릭.
3. Provider 드롭다운에서 사전에 등록한 GenON Qwen 3.5 397B 선택.
4. Save 클릭. 셀에 provider 이름이 표시되면 성공입니다.
5. 같은 절차로 agent, briefing, ontology_mapper, document_processing 행도 채워주세요.

시나리오 2 — 특정 워크스페이스만 다른 provider 사용

finance-invest 워크스페이스만 브리핑 use-case 에 다른 모델을 쓰고 싶다면:

1. briefing 행 × finance-invest 열 셀의 + 클릭.
2. Provider 선택 + 필요 시 model_override / max_tokens_override 입력.
3. Save 클릭.

이후 finance-invest 워크스페이스의 브리핑 호출만 새 provider 로 라우팅됩니다. 다른 워크스페이스는 그대로 Global 을 사용합니다.

시나리오 3 — 워크스페이스 override 해제

위에서 추가한 override 를 없애고 Global 기본값으로 되돌리려면:

1. 해당 셀의 삭제 아이콘 클릭.
2. 확인 다이얼로그에서 삭제 클릭.
3. 셀이 비워지고, 호출은 자동으로 Global 셀의 provider 로 fall-through 됩니다.

참고: VLM(이미지 캡션) 이나 외부 상용 LLM 을 추가로 묶고 싶다면, 먼저 /admin/llm-providers 에서 해당 provider 등록 + Vault 키 설정이 끝나 있어야 합니다. 본 가이드는 LLM 기본 예시(GenON Qwen 3.5 397B)만 다룹니다.

API 직접 호출 (선택)

UI 대신 스크립트로 일괄 설정하고 싶을 때 쓰는 예시입니다.

현재 매트릭스 조회

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

curl -sS "https://gend.genon.ai/api/v1/admin/llm-bindings" \
  -H "Authorization: Bearer $TOKEN" | jq

Global chat 바인딩 추가

PROVIDER_ID=$(curl -sS "https://gend.genon.ai/api/v1/admin/llm-providers" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.[] | select(.name=="GenON Qwen 3.5 397B") | .id')

curl -sS -X POST "https://gend.genon.ai/api/v1/admin/llm-bindings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"use_case\": \"chat\",
    \"workspace_id\": null,
    \"provider_id\": \"$PROVIDER_ID\"
  }"

응답에서 id 를 받으면 등록 성공입니다.

현재 적용되는 provider 확인 (디버그)

curl -sS "https://gend.genon.ai/api/v1/llm-bindings/effective?use_case=chat&workspace_slug=finance-invest" \
  -H "Authorization: Bearer $TOKEN" | jq

응답의 resolved_from 필드로 어느 tier(워크스페이스/global/env)에서 매칭됐는지 확인할 수 있습니다.

자주 묻는 질문 / 문제 해결

Q1. 셀을 채웠는데 AI 호출이 여전히 기존 provider 로 갑니다. A. 호출자가 코드/파이프라인 설정으로 직접 override 를 넘기고 있을 수 있습니다. /api/v1/llm-bindings/effective 로 실제로 어떤 provider 가 선택되는지 확인하세요. resolved_from 가 override 면 파이프라인 설정 쪽을 비워야 합니다.

Q2. provider 를 삭제하려는데 "다른 곳에서 사용 중" 오류가 납니다. A. 그 provider 를 참조하는 바인딩이 남아 있어서 보호 차원에서 삭제가 막힙니다. 매트릭스에서 해당 provider 가 채워진 셀을 모두 다른 provider 로 바꾸거나 비운 후 다시 삭제하세요.

Q3. 같은 use-case + 같은 워크스페이스에 두 개를 만들 수 있나요? A. 안 됩니다. 동일 셀에 중복 등록 시 409 응답을 받습니다. 기존 항목을 수정하거나 삭제 후 다시 만드세요.

Q4. 워크스페이스를 삭제하면 그 워크스페이스 바인딩은 어떻게 되나요? A. 자동으로 함께 정리됩니다. 별도 정리 작업이 필요 없습니다.

Q5. 한 워크스페이스에서 disabled 된 provider 를 가리키고 있으면 어떻게 되나요? A. 호출 시점에 해당 셀은 무시되고 자동으로 Global → env 순서로 fall-through 됩니다. 사용자가 에러를 보지 않도록 fail-soft 동작합니다. 단, 운영자는 가능한 한 빨리 셀을 다른 provider 로 교체해 주세요.

함께 보면 좋은 문서

• LLM Providers — provider 등록 (Vault 키 포함)
• LLM Admin UI — Admin 전체 흐름 한 화면 요약
• Workspace LLM Settings — 워크스페이스 admin 의 자율 설정
• LLM Workspace Quota — 워크스페이스 별 호출량 한도
• LLM Usage — 호출량/비용 모니터링