OpenAI 호환 서비스 (OpenAI-Compatible)¶

Backend.AI GO의 아키텍처는 OpenAI API 표준을 기반으로 구축되었습니다. 즉, OpenAI뿐만 아니라 "OpenAI 방언"을 사용하는 모든 서비스나 로컬 서버에 연결할 수 있습니다.

무엇을 연결할 수 있나요?¶

광범위한 도구 및 프로바이더 생태계와 연결할 수 있습니다:

로컬 추론 서버: Ollama, LocalAI, LM Studio, Text Generation WebUI (Oobabooga).
서드파티 API: Groq, DeepSeek, Together AI, Perplexity, Anyscale.
엔터프라이즈 게이트웨이: MLflow, Azure OpenAI (프록시 경유), 사내 기업용 게이트웨이.

연결 방법¶

프로바이더 탭으로 이동합니다.
프로바이더 추가를 클릭합니다.
프로바이더 유형으로 Custom OpenAI-Compatible을 선택합니다. OpenAI (GPT) 바로 아래에 있습니다.

이런 엔드포인트에는 OpenAI (GPT) 유형을 사용하지 마세요. 이 유형에는 베이스 URL 입력란이 없고 키를 항상 https://api.openai.com에서 확인하므로, 다른 서버의 토큰은 거부됩니다. 검증에 실패하면 오류 메시지 앞에 확인한 URL이 표시되고, 입력한 키가 OpenAI 키 형식이 아니면 설정 화면에서 Custom OpenAI-Compatible을 안내합니다.
세부 정보를 입력합니다:
- 베이스 URL: API 엔드포인트의 전체 URL입니다 (보통 /v1으로 끝납니다).
  - 예시 (Ollama): http://localhost:11434/v1
  - 예시 (DeepSeek): https://api.deepseek.com/v1
  - 두 형태 모두 동작합니다. 이미 API 루트(/v1, /openai)로 끝나는 Base URL은 자동으로 인식되므로 /v1/v1/models처럼 경로가 중복되지 않습니다.
- API 키: 인증 토큰입니다. 사용자 지정 엔드포인트에서는 선택 사항입니다. Ollama처럼 인증이 아예 필요 없는 자체 호스팅 서버가 많으므로, 필드를 비워둔 채로 연결 테스트를 눌러 엔드포인트가 정상적으로 응답하는지 확인할 수 있습니다. 서버가 키를 요구하지만 실제로 검증하지는 않는 경우라면 아무 문자열이나 입력해도 됩니다 (예: sk-dummy).
모델 발견: Backend.AI GO는 엔드포인트에서 사용 가능한 모델 목록을 가져오려고 시도합니다. 자동 발견이 실패하면 모델 이름을 수동으로 입력해야 할 수도 있습니다.
모델 선택: 마법사의 모델 선택 단계에서 엔드포인트가 보고한 모델 목록이 표시됩니다. 알려진 기본 모델은 미리 체크되어 있으며, 선택을 조정한 뒤 설정 완료를 클릭하세요. 선택한 모델은 프로바이더 카드를 열지 않아도 채팅 모델 선택기에 바로 나타납니다. 나중에 선택을 누르면 선택 없이 프로바이더가 추가되며(Backend.AI GO가 감지할 수 있는 기본 모델을 채워 넣고, 모델은 나중에 프로바이더 카드에서 선택할 수 있습니다). 카탈로그를 사용할 수 없는 경우 해당 안내가 표시되고 그래도 완료할 수 있습니다.

실행 비용과 실제 응답한 모델¶

일부 OpenAI 호환 서비스는 각 응답에 든 비용을 함께 보고합니다. 예를 들어 OpenRouter는 모든 응답의 usage.cost에 미국 달러 단위 비용을 담아 보냅니다. 응답에 이 값이 있으면 에이전트 실행은 두 곳에서 이 값을 사용합니다.

지출 한도: 보고된 비용이 지출 한도 규칙에 합산됩니다. openrouter/auto처럼 서비스가 요청마다 모델을 고르는 경우에는 고정 가격이 존재하지 않으므로, 보고된 비용이 지출 규칙을 발동시킬 수 있는 유일한 값입니다.
실행 상세: 실행에 표시되는 비용이 보고된 값입니다. 비용 위에 마우스를 올리면 프로바이더가 보고한 값인지, 모델 가격표로 추정한 값인지 확인할 수 있습니다.

비용이 보고되지 않은 응답은 이전과 같이 모델 가격표로 계산합니다. 음수이거나 형식이 잘못된 값은 0으로 계산하지 않고 무시합니다.

서비스가 요청한 모델과 다른 모델로 응답하면, 실행 상세의 실제 응답 모델 항목에 실행을 실제로 처리한 모델이 표시됩니다. openrouter/auto를 요청한 실행이 어떤 모델의 응답을 받았는지 여기서 확인할 수 있습니다.

요청 확장¶

엔드포인트에 따라 모든 요청에 추가 필드나 헤더가 필요한 경우가 있는데, vLLM 서버의 chat_template_kwargs, OpenRouter의 프로바이더 라우팅 설정과 HTTP-Referer, X-Title 헤더, API 게이트웨이의 테넌트 헤더 같은 것들입니다. 프로바이더를 추가한 뒤 카드의 편집을 눌러 화면 아래쪽의 요청 확장을 열고 설정하면, 라우터가 이 프로바이더로 보내는 모든 요청에 덧붙입니다.

추가 본문(기본값): 요청 본문에 병합되는 JSON 객체입니다. 클라이언트가 이미 보낸 필드는 클라이언트 값이 유지됩니다.
본문 재정의: 요청 본문에 병합되며 클라이언트가 보낸 값을 대체하는 JSON 객체입니다. OpenRouter의 {"provider": {"data_collection": "deny"}}처럼 클라이언트가 바꾸면 안 되는 정책에 씁니다.
추가 헤더: 한 줄에 Name: value 하나씩 적습니다. 헤더 값은 API 키처럼 저장되고 저장한 뒤에는 다시 표시되지 않습니다. 프로바이더를 편집할 때 저장된 헤더는 가려진 채로 보이는데, 그 줄을 그대로 두면 저장된 값이 유지됩니다.

중첩된 객체는 키 단위로 병합되므로 provider.data_collection을 재정의해도 클라이언트의 provider.sort는 남고, 배열과 단일 값은 통째로 바뀝니다.

라우터는 저장하기 전에 이 설정을 검사해서, 라우터가 직접 쓰는 필드(model, messages, stream 등)와 직접 설정하는 헤더(Authorization 등)를 거부합니다. 거부 사유는 거부된 필드 이름과 함께 설정 화면에 표시됩니다. 요청 확장을 저장하려면 라우터가 실행 중이어야 하고, 헤더를 바꾸면 새 값을 반영하도록 라우터가 다시 시작됩니다.

명령줄에서는 aigo provider add 또는 aigo provider update로 같은 항목을 설정합니다.

aigo provider update <id> \
  --extra-body '{"chat_template_kwargs": {"enable_thinking": false}}' \
  --header "X-Title: Backend.AI GO"

--extra-body-override는 본문 재정의를 설정하고, --extra-body-file과 --extra-body-override-file은 파일에서 JSON 객체를 읽으며(-는 표준 입력), --header는 여러 번 쓸 수 있습니다.

예시¶

Ollama 연결하기¶

Ollama가 다른 컴퓨터(또는 로컬 포트)에서 실행 중인 경우:

베이스 URL: http://<ip-address>:11434/v1
API 키: ollama (또는 허용된 경우 비워둠)

Groq 연결하기¶

Groq의 LPU를 사용한 초고속 추론을 위해:

베이스 URL: https://api.groq.com/openai/v1
API 키: Groq API 키

이러한 유연성 덕분에 Backend.AI GO는 모든 AI 요구 사항을 위한 만능 프론트엔드가 됩니다.