AI 모델

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

작동 내용

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

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

소스 제공업체의 이용약관을 먼저 확인하십시오

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

AI Models는 AI Chat and AI Agent(AI 모듈, AI providers 참조)와 별개의 제품입니다. 두 모듈은 서로 종속되지 않습니다.

요구 사항

항목	요구 사항
모듈	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나 모델 파일은 필요하지 않습니다.

인프라 준비

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에서 연결

1. 모듈 켜기

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

2. 공급자 추가

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. 연결 테스트

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

4. 모델 동기화

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

5. 가격 설정 및 모델 활성화

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

6. 라우트 및 페일오버

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

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

7. 판매 스위치 켜기

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

고객이 이용할 수 있는 기능

고객 포털의 AI › API:

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

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

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

지갑 및 결제

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

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

확인

1. 3단계를 완료하면 Test connection에 ok 및 모델 수가 표시됩니다.

2. 4단계를 완료하면 새 모델이 비활성화 상태 및 가격 미지정 상태로 목록에 표시됩니다.

3. 잔액이 충전된 지갑을 보유한 고객 계정으로 키를 생성하고 게이트웨이를 호출합니다.

   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이(가) 반환됩니다.

제한 사항 및 참고 사항

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

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 오류 발생	지갑 잔액이 최소 기준 미만이거나 요청에 부족합니다. 고객에게 충전을 요청하십시오.