AI 공급자

관리자 위치: System › Settings › AI provider (/settings/ai). AI 모듈 스위치는 해당 위치와 System › Admin › License & updates (/license)의 Module 카드에도 있습니다.

작동 내용

AI Chat(자동 고객지원 채팅)과 AI Agent(자연어 기반 VM 관리)에는 모델이 내장되어 제공되지 않습니다. 자체 제공업체를 직접 선택할 수 있습니다. OpenAI, OpenRouter, LiteLLM 게이트웨이 또는 자체 vLLM 서버처럼 OpenAI 호환 chat/completions API를 제공하는 모든 서비스가 해당합니다. NexCMP는 엔드포인트와 API key(암호화됨)를 저장하고 모든 AI 기능에 이를 사용합니다. 요금은 해당 제공업체에 직접 지불합니다.

요구 사항

항목	요구 사항
Endpoint	OpenAI 호환 기본 URL(https://api.openai.com/v1, https://ai.example.com/v1). NexCMP는 /chat/completions을(를) /v1(으)로 끝나는 URL에 추가하며, 그 외 다른 URL에는 /v1/chat/completions을(를) 추가합니다. 이미 /chat/completions(으)로 끝나는 URL은 그대로 사용됩니다.
모델	도구(함수) 호출을 지원하는 모델입니다. AI Chat과 Agent 모두 이 모델을 사용합니다.
API 키	해당 엔드포인트의 키입니다. 공급자 측에 지출 한도가 설정된 키를 사용하는 것이 좋습니다 (예: 월별 예산이 설정된 LiteLLM 가상 키).
네트워크	패널 서버는 HTTP(S)를 통해 엔드포인트에 도달할 수 있어야 합니다. 양식에 입력된 URL은 포트 80, 443, 8080 또는 8443의 인터넷 주소만 허용되며, 내부 주소를 사용하려면 먼저 공급자를 저장한 후 테스트하세요.
의존성	AI 모듈이 켜져 있어야 합니다. Agent에 대해서는 AI Agent를 참고하세요.

인프라 준비

1. 공급자에 가입하고 API 키를 생성합니다. 공급자가 예산 또는 요청 수 제한을 지원하는 경우 월별 한도를 설정하세요.

2. 기본 URL과 정확한 모델 이름(선택 사항으로 최대 4개의 대체 모델)을 기록해 둡니다.

3. 입력하기 전에 NexCMP 서버에서 테스트합니다:

   curl -s https://ai.example.com/v1/chat/completions \
     -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \
     -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}'

   choices[0].message.content이(가) 포함된 JSON 응답은 엔드포인트가 작동함을 의미합니다.

NexCMP에서 연결

1. System › Settings › AI provider를 엽니다.

2. Module AI 카드에서 모듈을 켜짐으로 전환합니다. 켜질 때까지 고객은 포털에서 AI Chat이나 AI Agent를 볼 수 없습니다. (License & updates에서도 전환할 수 있습니다.)

3. Connection 카드에서 다음을 입력합니다:

   필드	예시	참고
   이 공급자 사용	on	켜려면 기본 URL, 모델 및 키가 필요합니다.
   Display name	LiteLLM	최대 60자.
   기본 URL (OpenAI 호환)	https://ai.example.com/v1	http:// 또는 https://, 최대 300자, 공백 없음.
   공급자 API 키	sk-XXXX	암호화되어 저장되며, 이후에는 마지막 4자만 표시됩니다. 저장된 키를 유지하려면 비워 둡니다.
   기본 모델	gpt-4o-mini	문자, 숫자 및 - _ . / : @.
   대체 모델	gemini-2.5-flash	쉼표로 구분, 최대 4개. 기본 모델이 실패할 때 사용됩니다.
   추론 수준	기본값 (전송되지 않음)	Minimal, Low, Medium 또는 High. 추론 모델(Gemini, o-series)의 경우 낮은 수준에서 훨씬 빠르게 응답합니다. 일반 모델의 경우 기본값으로 두세요.

4. Save를 클릭한 다음 Test connection을 클릭합니다. 테스트는 짧은 질문 하나를 보내고 Connected — <model>, <ms> ms 또는 공급자가 반환한 오류를 표시합니다.

저장 시 수행되는 작업

• 공급자 설정은 하나의 구성 항목으로 저장되며, 키는 설치 마스터 키를 사용하여 이 목적에 맞게 바인딩된 AES-256-GCM으로 암호화됩니다.
• 지원 설정인 Primary model 및 Fallback model(AI Chat에서 사용)이 기본 모델 및 첫 번째 대체 모델로 자동 설정됩니다.
• 변경 사항이 감사 로그에 기록됩니다 (엔드포인트, 모델, 키 변경 여부 — 키 자체는 기록되지 않음).

확인

1. Test connection이 초록색으로 표시됩니다.
2. 테스트 고객으로 포털에 로그인합니다. 이제 메뉴에 AI Chat(또는 채팅 말풍선)과 AI Agent가 표시됩니다.
3. AI Chat에 "내 잔액이 얼마인가요?"라고 물어봅니다. 실제 잔액을 알려주는 응답이 오면 공급자가 도구 호출을 올바르게 처리하고 있음을 의미합니다.

한도 및 참고 사항

• 단일 공급자. NexCMP는 Chat, Agent 및 티켓 조사를 위해 단일 구성된 공급자를 사용합니다. 대체 모델은 해당 공급자 내에서 복원력을 제공합니다.
• 키 안전성. 저장된 키는 저장된 엔드포인트로만 전송됩니다. 기본 URL을 변경하는 경우 테스트하기 전에 키를 다시 입력해야 합니다.
• 고객별 제한. AI Chat은 로그인한 고객 전용이며, 분당 및 채팅당 메시지 제한이 적용됩니다. 에이전트는 계정당 일일 호출 제한이 있습니다. AI Chat 및 AI Agent을 참조하세요.
• 개인정보 보호. 고객의 질문과 AI가 해당 고객을 위해 읽는 데이터(읽기 전용)는 제공업체로 전송됩니다. 개인정보처리방침에 이를 명시하세요.
• 비용 제어. NexCMP는 AI 비용을 측정하지 않으며, 제공업체의 예산 기능을 사용해야 합니다.
• 모듈은 언제든지 끌 수 있습니다. AI 메뉴 항목이 사라지고 AI 라우트는 404를 반환합니다 module_disabled. AI Chat의 일부 백그라운드 작업(티켓 조사, 지연 답변)은 패널을 다시 시작할 때 변경 사항을 반영합니다.

Troubleshooting

증상	원인	해결 방법
base_url must be an http(s) URL	스키마 누락 또는 공백	https://host/v1을 사용하십시오.
api_key is required to enable the provider	저장된 키 없음	키를 입력하고 저장하세요.
base_url and model are required to enable the provider	빈 필드	둘 다 입력하세요.
"Base URL 차단됨: public http(s)만 허용되며, 포트는 80/443/8080/8443임"	저장되지 않은 내부 주소 또는 다른 포트 테스트 중	먼저 제공업체를 저장한 후 테스트하세요.
api_key is required (enter the key again when you change the endpoint)	Base URL이 저장된 값과 다름	키를 다시 입력하세요.
model: letters, digits and - _ . / : @	잘못된 문자	제공업체의 정확한 모델 ID를 사용하세요.
fallback_models: up to 4 model names	너무 많음	4개 이하로 유지하세요.
401 오류로 테스트 실패	Wrong key	키와 엔드포인트를 확인하세요.
404 또는 "model not found" 오류로 테스트 실패	잘못된 경로 또는 모델	Base URL(/v1)과 모델 ID를 확인하세요.
Too many tests — wait a minute (429)	분당 10회 초과 테스트	잠시 기다리세요.
포털에 여전히 AI 메뉴가 표시되지 않음	모듈이 꺼져 있거나 제공업체가 "사용 중" 상태가 아님	모듈을 켜고 제공업체를 활성화하세요.