---
title: AI 공급자
description: AI Chat 및 AI Agent를 위해 OpenAI 호환 AI 엔드포인트 연결 — AI 모듈 켜기, 엔드포인트 및 키 입력, 테스트 및 제한 설정.
url: https://nexcmp.com/ko/docs/ai/ai-providers/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI 공급자 {#ai-provider}

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

## 작동 내용 {#what-it-does}

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

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 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](https://nexcmp.com/ko/docs/ai/ai-agent/#requirements)를 참고하세요. |

## 인프라 준비 {#prepare-the-infrastructure}

1. 공급자에 가입하고 API 키를 생성합니다. 공급자가 예산 또는 요청 수 제한을 지원하는 경우 월별 한도를 설정하세요.
2. **기본 URL**과 정확한 **모델 이름**(선택 사항으로 최대 4개의 대체 모델)을 기록해 둡니다.
3. 입력하기 전에 NexCMP 서버에서 테스트합니다:

   ```bash
   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에서 연결 {#connect-in-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` 또는 공급자가 반환한 오류를 표시합니다.

![AI 모듈이 켜져 있고 연결 양식에 예시 값이 입력된 AI provider 페이지](https://nexcmp.com/ko/docs/images/ai/ai-providers-01-connection.webp)


### 저장 시 수행되는 작업 {#what-saving-does}

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

## 확인 {#verify}

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

## 한도 및 참고 사항 {#limits-notes}

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

## Troubleshooting {#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 메뉴가 표시되지 않음 | 모듈이 꺼져 있거나 제공업체가 "사용 중" 상태가 아님 | 모듈을 켜고 제공업체를 활성화하세요. |