---
title: AI 모델
description: 자체 게이트웨이로 AI 모델 판매: OpenAI/Anthropic 호환 공급자 추가, 모델 동기화, 가격 설정 후 고객이 자체 키와 지갑으로 단일 엔드포인트를 호출합니다.
url: https://nexcmp.com/ko/docs/infrastructure/ai-models/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI 모델 {#ai-models}

> **관리자 위치:** System › Admin › License & updates (`/license`)에서 모듈을 활성화합니다. 그런 다음 Services › AI Models의 Providers (`/ai/providers`), Models (`/ai/models`), Profit (`/ai/profit`) 및 Audit (`/ai/audit`) 메뉴로 이동합니다. 고객은 고객 포털의 AI › API를 사용합니다.

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

AI Models는 자체 패널에서 구동되는 게이트웨이 및 과금 레이어입니다. 고객은 API 키를 발급받아 OpenAI 호환 또는 Anthropic 호환 형식으로 **자체 도메인의 단일 엔드포인트**를 호출합니다. 제공할 모델과 1백만 토큰당 비용을 직접 선택할 수 있습니다. NexCMP는 키, 제한 한도 및 지갑을 확인하고, 추가된 공급자에게 요청을 전송하며, 토큰 사용량을 측정하여 고객의 선불 지갑에서 요금을 차감합니다.

**모델 소스는 직접 준비해야 합니다.** NexCMP는 공급자, 모델, 기본 주소 및 가격을 기본으로 제공하지 않습니다. 모델, API 키, 토큰 또는 공급자 계정을 제공하지 않습니다.

::: warning 소스 제공업체의 이용약관을 먼저 확인하십시오
많은 모델 소스가 재판매나 제3자에 대한 액세스 권한 양도를 제한합니다. 사용 및 재판매 권한이 승인된 소스만 사용해야 하며, 해당 소스의 이용약관과 적용되는 법률을 준수하십시오. 본 페이지의 내용은 법률적 조언이 아닙니다.
:::

AI Models는 **AI Chat and AI Agent**(**AI** 모듈, [AI providers](https://nexcmp.com/ko/docs/ai/ai-providers/) 참조)와 별개의 제품입니다. 두 모듈은 서로 종속되지 않습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 모듈 | License & updates, Modules에서 **AI Models** 활성화(기본값은 비활성화). |
| Providers | 재판매 권한이 있는 하나 이상의 모델 소스로, 각각 OpenAI 호환 API(`/chat/completions`), Anthropic 호환 API(`/messages`) 또는 둘 다를 갖추고 있어야 합니다. 각 소스마다 base URL과 API key가 필요합니다. |
| 네트워크 | 패널은 퍼블릭 도메인 이름을 통해 **포트 443의 HTTPS**로 각 공급자에 연결할 수 있어야 합니다. 내부 호스트, 다른 포트 또는 일반 HTTP를 사용하는 공급자는 **Allowed internal hosts**(설정 `ai_endpoint_allow`)에 등록해야 합니다. |
| 고객 | 이메일 인증이 완료되고 지갑 잔액이 충전된 고객 계정. |
| 하드웨어 | 없음. NexCMP는 요청 전달만 수행하며, GPU나 모델 파일은 필요하지 않습니다. |

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

1. 사용할 각 모델 소스에서 API 키를 발급받고 기본 URL(예: `https://api.example.com/v1`)을 확인합니다.
2. 재판매 관련 소스 이용약관을 확인합니다.
3. 소스가 내부 네트워크에서 실행되는 경우 해당 주소(예: `http://10.0.0.5:8000/v1`)를 결정합니다. `10.0.0.5:8000` 주소를 **Allowed internal hosts**에 등록해야 합니다.

## NexCMP에서 연결 {#connect-in-nexcmp}

### 1. 모듈 켜기 {#_1-turn-the-module-on}

**System › Admin › License & updates**를 열고 **Module** 카드를 찾은 뒤 **AI Models**를 켭니다. 메뉴가 새로고침되면서 **Services › AI Models**이 표시됩니다. 모듈이 꺼져 있는 동안 고객 페이지, 관리자 페이지 및 게이트웨이는 모두 `404 module_disabled` 응답을 반환하며 공급자에게 요청을 전송하지 않습니다.

![AI Models 스위치가 켜진 Module 카드](https://nexcmp.com/ko/docs/images/infrastructure/ai-models-01-modules.webp)

### 2. 공급자 추가 {#_2-add-a-provider}

1. **AI Models › Providers**를 열고 **Add provider**를 선택합니다.
2. 짧은 **slug**, **name**(관리자에게만 표시됨), **type**(OpenAI 호환, Anthropic 호환 또는 둘 다), **base URL**, **API key** 및 **priority**(낮은 숫자가 먼저 시도됨)를 입력합니다.
3. 저장합니다. 키는 암호화되어 저장되며 이후에는 마지막 4자리만 표시됩니다. 키는 로그인한 관리자 세션에서만 입력할 수 있습니다.

두 가지 형식을 실제로 모두 지원하는 게이트웨이에만 **Both**를 사용하십시오. NexCMP는 두 형식 간의 변환을 지원하지 **않습니다**. OpenAI 호환 공급자가 제공하는 모델은 `/ai/v1/chat/completions`에서, Anthropic 호환 공급자가 제공하는 모델은 `/ai/v1/messages`에서 호출됩니다.

![유형, 우선순위, 상태가 포함된 3개의 샘플 공급자가 나열된 Providers 페이지](https://nexcmp.com/ko/docs/images/infrastructure/ai-models-02-providers.webp)

### 3. 연결 테스트 {#_3-test-the-connection}

공급자에서 **Test connection**을 선택합니다. NexCMP가 키를 사용하여 `GET <base URL>/models`을 읽고 **ok**를 보고하거나, 실패 이유(**auth**(잘못된 키), **blocked**, **billing**, **unreachable**)를 보고합니다. 테스트는 분당 6회로 제한됩니다.

### 4. 모델 동기화 {#_4-sync-the-models}

**Sync models**을 선택합니다. NexCMP가 공급자의 모델 목록을 읽어 각 새 모델을 **가격 없이 비활성화된 상태**로 추가합니다. 공급자 목록에서 제외된 모델에는 플래그가 지정됩니다. 모듈이 활성화되어 있는 동안 목록은 6시간마다 자동으로 동기화됩니다(설정 `ai_models_sync_hours`).

### 5. 가격 설정 및 모델 활성화 {#_5-set-prices-and-switch-models-on}

1. **AI Models › Models**을 엽니다.
2. 판매하려는 각 모델에 대해 1백만 토큰당 미국 달러 기준 **판매 가격**을 설정합니다: **입력**, **캐시된 입력** 및 **출력**.
3. 선택 사항으로 모델의 **원가**를 입력할 수 있습니다. 입력 시 **Profit**에 일별 및 모델별 원가 대비 수익이 표시되며, 원가에 최소 마진(설정 `ai_min_margin_pct`, 기본값 10)을 더한 금액 미만의 판매 가격은 의도적인 손실을 확인하지 않는 한 거부됩니다. **Set price from cost**는 직접 선택한 마진율을 적용하며 기본 마진율은 없습니다.
4. 모델을 활성화합니다. 판매 가격이 없는 모델은 활성화할 수 없습니다. 0으로 남겨둔 cached input 가격에는 input 가격이 적용됩니다.

![input, cached input, output 판매 가격 및 온오프 스위치가 표시된 Models 페이지](https://nexcmp.com/ko/docs/images/infrastructure/ai-models-03-models.webp)

### 6. 라우트 및 페일오버 {#_6-routes-and-failover}

모델에서 **Routes**는 해당 모델을 제공하는 공급자를 순서대로 나열합니다. 보조 공급자를 대체 수단으로 추가하고, 순서를 설정하며, 필요에 따라 공급자마다 다른 모델 이름을 지정할 수 있습니다(공급자에게 전달되는 이름은 공개하는 이름과 달라도 무방합니다). 공급자가 서버 오류, 인증 또는 결제 오류, 모델 누락, 속도 제한을 반환하면 NexCMP는 다음 라우트를 시도합니다. 요청이 전송된 후 읽기 타임아웃이 발생한 경우 이중 결제를 방지하기 위해 다른 공급자에게 요청을 전송하지 **않습니다**.

각 공급자의 요청 속도는 분당 `ai_provider_rpm`회로 조절됩니다(기본값 50). 공급자가 인증 또는 결제 오류를 계속 반환할 경우, Telegram이 구성되어 있으면 NexCMP가 관리자에게 Telegram으로 알림을 보냅니다.

### 7. 판매 스위치 켜기 {#_7-open-the-sale-switch}

AI Models 페이지 상단의 **판매 스위치**(설정 `feature_ai_models`)는 기본적으로 꺼져 있습니다. 꺼져 있는 동안에는 고객에게 서비스가 아직 오픈되지 않은 것으로 표시되며 공개 가격표에도 이용 불가로 안내됩니다. 최소 하나의 모델이 켜져 있고 판매 가격과 키가 있는 라우트가 설정되어 있는지 확인한 후 스위치를 켭니다.

### 고객이 이용할 수 있는 기능 {#what-customers-can-do}

고객 포털의 **AI › API**:

- **Models**: 모델 및 가격, 기본 URL, 바로 사용할 수 있는 예제 명령어를 표시합니다.
- **API Keys**: 키를 생성, 이름 변경, 순환, 비활성화 및 삭제합니다. 시크릿은 한 번만 표시되며 해시만 저장됩니다. 키별 설정: 허용 모델, 만료일, 소프트 예산(경고) 및 하드 예산(`402`으로 차단), 분당 요청 수, 분당 토큰 수.
- **Usage**: 모델별, 키별, 일별 사용량(내보내기 지원).
- **Logs**: 필터링 가능한 요청 기록(시간, 키, 모델, 토큰, 비용, 상태, 지연 시간). **프롬프트와 응답은 기록되지 않습니다.** 로그는 기본적으로 90일 동안 보관됩니다(`ai_log_retention_days`).
- **Settings**: 계정 예산 및 예산 알림용 이메일 주소.
- **Playground**: 모델과 대화하고, 모델을 나란히 비교하며, 해당하는 코드를 복사합니다.

![두 가지 API 형식의 기본 URL이 표시된 고객 API Keys 페이지](https://nexcmp.com/ko/docs/images/infrastructure/ai-models-04-keys.webp)

도메인의 게이트웨이 엔드포인트:

```text
POST /ai/v1/chat/completions      OpenAI-compatible
POST /ai/v1/messages              Anthropic-compatible (also /ai/v1/messages/count_tokens)
GET  /ai/v1/models                model list
GET  /ai/v1/models/pricing        public price list, no key needed
```

### 지갑 및 결제 {#wallet-and-billing}

AI 사용 요금은 다른 모든 서비스와 동일한 선불 지갑에 청구됩니다. 요청이 공급자에게 전달되기 전에 NexCMP는 요청에서 발생할 수 있는 최대 비용을 예약합니다. 잔액이 최소 금액(`ai_min_balance_cents`, 기본값 20센트) 미만이거나 부족한 경우 요청은 `402 insufficient_balance`과 함께 거부되며 **공급자를 호출하지 않습니다**. 사용량은 계정별로 수집되어 매시간 이후 지갑 원장 항목으로 정산되고 5분마다 sweep 작업이 수행되며, 아직 정산되지 않은 사용량은 게이트웨이가 확인하는 잔액에서 이미 차감됩니다.

리셀러는 자체 도메인에서 AI Models를 판매할 수 있습니다. 리셀러의 마크업 또는 할인이 판매 가격에 적용되며 도매 지갑에서 도매 가격이 차감됩니다. 기본적으로 활성화된 리셀러별 AI 스위치로 판매 여부를 제어합니다.

## 확인 {#verify}

1. 3단계를 완료하면 **Test connection**에 **ok** 및 모델 수가 표시됩니다.
2. 4단계를 완료하면 새 모델이 비활성화 상태 및 가격 미지정 상태로 목록에 표시됩니다.
3. 잔액이 충전된 지갑을 보유한 고객 계정으로 키를 생성하고 게이트웨이를 호출합니다.

   ```bash
   curl https://your-domain/ai/v1/chat/completions \
     -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \
     -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}'
   ```

   `200` 응답에 모델의 답변이 포함됩니다. **Usage**에 요청 내역이 표시되며 원가를 입력한 경우 **Profit**에도 표시됩니다.
4. 지갑 잔액이 0인 상태에서 동일한 호출을 실행하면 `402 insufficient_balance`이(가) 반환됩니다.

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

- 이 모듈에는 공급자, 모델 또는 가격이 내장되어 있지 않으며, 공급자로부터 가격표를 읽어오지 않습니다.
- 웹 검색 등 공급자 측에서 실행되고 호출당 요금이 부과되는 도구는 사용량을 측정할 수 없으므로 거부됩니다. 제한된 요청 파라미터 목록만 전달됩니다.
- 토큰 사용량은 공급자의 응답에서 가져오며, 응답에 사용량이 없는 경우 NexCMP가 이를 추정하여 해당 기록을 추정치로 표시합니다.
- 공급자로부터 반환된 오류는 고객에게 전달되기 전에 정리됩니다(이름, 호스트, 주소 및 공급자의 모델 이름 제거). 고객에게는 어떤 공급자가 요청을 처리했는지 노출되지 않습니다.
- 고객은 관리 패널의 도메인을 통해 게이트웨이에 접속하므로 해당 도메인의 TLS가 정상 작동해야 합니다.
- NexCMP는 이 모듈에 대해 서비스 수준 계약(SLA), 파인튜닝 또는 GPU 호스팅을 제공하지 않습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 및 해결 방법 |
|---|---|
| 모든 AI Models 페이지 및 게이트웨이에서 `404 module_disabled` 반환 | 모듈이 비활성화되어 있습니다. License & updates, Modules에서 **AI Models**을 활성화하십시오. |
| `endpoint_host_not_allowed`, `endpoint_must_be_https` 또는 `invalid_endpoint_port` 오류와 함께 공급자 추가 실패 | 기본 URL은 공용 도메인 이름의 443 포트에서 HTTPS여야 합니다. 내부 호스트, 다른 포트 또는 일반 HTTP의 경우 `host:port`을 **Allowed internal hosts** 아래에 등록하십시오. |
| `blocked_endpoint` | 주소가 IP이거나 도메인 이름이 사설 IP 주소로 확인됩니다. 의도한 구성인 경우 **Allowed internal hosts**에 등록하십시오. |
| **Test connection** 실행 시 `auth` 표시 | 키가 잘못되었거나 접근 권한이 없습니다. 키를 다시 입력하십시오. |
| 모델을 활성화할 수 없음(`no_price`) | 먼저 판매 가격을 설정하십시오. |
| 고객에게 `503 ai_unavailable` 오류 발생 | 판매 스위치가 꺼져 있거나 리셀러의 AI 스위치가 꺼져 있습니다. |
| 고객에게 `503 upstream_unavailable` 오류 발생 | 요청된 형식으로 해당 모델을 제공하는 활성화된 라우트(키 포함)가 없습니다. 모델의 라우트 및 공급자 유형을 확인하십시오. |
| 고객에게 `402 insufficient_balance` 오류 발생 | 지갑 잔액이 최소 기준 미만이거나 요청에 부족합니다. 고객에게 충전을 요청하십시오. |