커스텀 OpenAI 호환 LLM 프로바이더로 Onyx 실행하기.

빠른 답: 관리자 패널에서 Add Custom LLM Provider.

Onyx의 문서는 OpenAI 호환 엔드포인트를 노출하기만 하면 커스텀 프로바이더가 작동한다고 명시하며, 예시 Base URL 형태도 정확히 게이트웨이 스타일인 https://yourprovider.com/v1입니다. 흐름은 다음과 같습니다: 프로필 아이콘에서 Admin Panel을 열고 Configuration으로 간 다음 Language Models로 가서 Add Custom LLM Provider를 선택하세요. 이 폼에서 중요한 결정은 네 가지입니다. Display Name은 장식일 뿐입니다. Provider Name은 LiteLLM 프로바이더 키와 일치해야 합니다. Onyx가 내부적으로 LiteLLM을 통해 모델 호출을 라우팅하기 때문입니다; OpenAI 호환 게이트웨이의 경우 그것은 openai입니다. Base URL은 /v1 접미사를 포함한 게이트웨이 엔드포인트입니다. 그리고 Model Configurations 섹션은 사용 가능하게 만들고 싶은 각 모델 id를 카탈로그가 서빙하는 그대로 정확히 등록하는 곳입니다. 저장하고 기본값을 선택하면 채팅이 즉시 게이트웨이를 통해 라우팅됩니다.

Admin Panel -> Configuration -> Language Models
  -> Add Custom LLM Provider

Display Name:   APIsRouter
Provider Name:  openai            (LiteLLM provider key)
Base URL:       https://api.apisrouter.com/v1
API Key:        sk-YOUR-APISROUTER-KEY
Model Configurations:
  claude-sonnet-4-6
  claude-haiku-4-5-20251001
  deepseek-v4-pro

Onyx의 아키텍처에서 LLM이 앉는 자리.

Onyx(GitHub의 onyx-dot-app, 약 3.1만 스타, 예전 이름 Danswer)는 회사 지식을 위한 오픈소스 AI 플랫폼입니다: Slack, Google Drive, Confluence 등 수십 개의 커넥터로 소스를 인덱싱한 다음, 채팅 UI, 어시스턴트, 에이전트 워크플로우를 통해 그 위에서 질문에 답합니다. 가장 많이 배포된 셀프 호스팅 엔터프라이즈 검색 스택 중 하나이며, 바로 이 때문에 LLM 청구서가 기본값이 아니라 라우팅 결정을 받을 자격이 있습니다. 파이프라인은 깔끔하게 둘로 나뉩니다. 문서 임베딩과 리랭킹을 포함한 인덱싱과 검색은 기본적으로 로컬 모델로 Onyx 자체의 모델 서버에서 실행되며, 이 중 어느 것도 여러분의 LLM 프로바이더를 건드리지 않습니다. 답변 생성은 그 반대편입니다: 검색이 관련 구절을 조립하고 나면 LLM이 그것을 읽고 근거를 갖춘 응답을 쓰며, 그 호출이 LiteLLM을 거쳐 관리자가 설정한 프로바이더로 갑니다. 커스텀 프로바이더 플로우는 정확히 이 절반의 목적지를 바꿉니다. LiteLLM이 model id를 순수 문자열로 openai 타입 프로바이더에 전달하므로, Model Configurations에 등록하는 id는 Base URL 뒤 엔드포인트가 서빙하는 무엇이든 될 수 있습니다: 신중한 근거 답변에는 Claude, 볼륨에는 DeepSeek, 매우 긴 소스 컨텍스트에는 Gemini. 서로 다른 어시스턴트가 서로 다른 모델을 기본값으로 삼을 수 있으므로, 지원 어시스턴트와 엔지니어링 어시스턴트가 같은 프로바이더 항목을 통해 서로 다른 가격대를 탈 수 있습니다.

전체 설정, 그리고 손대지 않고 남는 것.

프로바이더 폼이 통합의 전부입니다; 편집할 설정 파일도, 다시 빌드할 컨테이너도 없습니다. 저장한 후 워크스페이스의 기본 모델을 설정하고, 원한다면 다른 품질 티어를 두고 싶은 어시스턴트마다 모델을 오버라이드하세요. 의도적으로 손대지 않고 남는 것: 커넥터는 자체 자격 증명을 유지하고, 인덱스는 영향받지 않으며, 검색을 위해 설정된 임베딩 모델도 이동하지 않습니다. 이 분리는 이 변경을 저위험으로 만드는 이유이기도 하므로 명시할 가치가 있습니다. 게이트웨이가 오작동해도 검색과 소스는 여전히 작동할 것입니다; 답변 생성만 오류가 나고, 기본값을 이전 프로바이더로 되돌리는 것은 드롭다운 하나면 됩니다. 배포를 자동화하는 팀을 위해, 같은 프로바이더 정의를 UI를 클릭하는 대신 Onyx의 API를 통해 시딩할 수도 있지만, 관리자 패널 경로가 문서화되고 안정된 표면이며 일회성 설정이 그 이상을 정당화하는 경우는 드뭅니다.

# confirm the gateway lists the ids you plan to register
curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

# confirm a chat completion works end to end
curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6",
       "messages":[{"role":"user","content":"ping"}]}'

근거를 갖춘 엔터프라이즈 답변을 위한 모델 선택.

Onyx 내부의 모델 평가는 유난히 구체적입니다: 같은 커넥터를 대상으로 같은 질문을 두 개의 다른 어시스턴트 기본값으로 물어보고 어느 답변이 올바른 구절을 인용하는지 비교하세요. 키별 사용량 로그가 두 후보 모두를 여러분의 실제 질문 조합으로 가격을 매겨줍니다.

• 근거를 갖춘 답변은 입력이 많습니다: 모델이 쓰는 답변보다 훨씬 많은 검색된 구절을 읽습니다. 그래서 입력 토큰당 가격이 출력 가격보다 질문당 비용을 더 크게 좌우합니다.
• claude-sonnet-4-6은 강력한 워크스페이스 기본값입니다: 검색된 소스 안에 머무는 데 엄격하고 문서에 없는 정책을 지어내는 데 저항합니다.
• 트래픽이 많은 어시스턴트(IT 헬프데스크, HR FAQ)는 claude-haiku-4-5-20251001이나 deepseek-v4-pro에서 잘 작동하며, 볼륨 가격이 좌석당 비용을 예측 가능하게 유지합니다.
• 긴 소스 문서는 롱컨텍스트 id에 유리합니다; 큰 설계 문서나 계약서를 컨텍스트로 끌어오는 어시스턴트라면 gemini-3.1-pro-preview를 테스트할 가치가 있습니다.
• 프로바이더 항목 하나에 여러 id를 등록하고 어시스턴트별로 배정하세요. 팀별 품질 티어가 하나의 전역 타협 모델보다 낫습니다.

사용한 만큼 지불 · 공식 요금보다 저렴

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Onyx 특유의 실패 패턴.

Provider Name은 자유 텍스트 라벨이 아닙니다. LiteLLM 프로바이더 키와 일치해야 하며, 게이트웨이의 경우 그 키는 openai입니다. 지어낸 이름은 폼이 문제없이 저장되더라도 요청 시점에 LiteLLM 프로바이더 오류로 실패합니다. Base URL은 /v1 접미사를 원합니다. Onyx 자체 문서가 /v1로 끝나는 엔드포인트 형태를 보여줍니다; 없으면 chat-completions 경로가 잘못 해석되어 게이트웨이에서 요청이 404가 됩니다. 모델 id는 Model Configurations에 존재합니다. 그곳에 등록한 적 없는 모델은 기본값으로 선택될 수 없으며, 등록된 id의 오타는 저장 시점이 아니라 첫 사용에서 model-not-found 오류로 드러납니다. 게이트웨이의 /v1/models 목록이 정답 표기입니다. 관리자 UI에 커스텀 모델 폼의 Base URL 필드가 없다면, 기능이 빠진 게 아니라 2026년 일부 릴리스에서 보고된 UI 회귀를 겪은 것입니다; 업그레이드하면 필드가 복원됩니다. 그리고 어느 절반을 옮겼는지 기억하세요: 검색 결과가 이상하거나 오래된 것처럼 보인다면 그것은 인덱싱과 커넥터 문제이며 커스텀 프로바이더를 전혀 건드리지 않습니다. 생성된 답변만 게이트웨이를 통해 라우팅됩니다.

어떤 사람들이 게이트웨이를 통해 Onyx를 쓰는가.

• 벤더별 계정을 엔드포인트 하나, 키 하나, 워크스페이스나 부서에 깔끔하게 매핑되는 키별 사용량으로 대체하는 셀프 호스팅 팀.
• 내부 검색을 위해 Onyx를 표준화하고 별도의 Anthropic 청구 관계 없이 Claude급 근거 답변을 원하는 엔터프라이즈.
• 등록된 모델 id를 통해 어시스턴트별로 가격이 매겨지는, 여러 품질 티어에서 여러 어시스턴트를 운영하는 플랫폼 팀.
• 동일한 코퍼스에서 모델 패밀리 간 답변 품질을 비교하는 평가자 — 각 후보는 새 프로바이더 통합이 아니라 등록된 id일 뿐입니다.
• 특정 벤더의 결제 수단에 접근할 수 없는 개발자. 카드 없이 충전만으로 사용할 수 있어 프로바이더별 가입 의존성이 사라집니다.

엔드포인트 검증 및 첫 채팅 디버깅.

폼을 건드리기 전에 위 두 curl 확인이 게이트웨이 절반을 커버합니다: 등록하려는 id가 /v1/models에 나타나야 하고, 직접적인 채팅 완성이 답해야 합니다. Onyx 내부에서는 실패가 빠르게 국지화됩니다. LiteLLM을 언급하는 프로바이더 오류는 Provider Name이 유효한 키가 아니라는 뜻입니다; openai로 설정하세요. 첫 채팅에서의 인증 오류는 API Key가 Base URL의 엔드포인트에 속하지 않는다는 뜻입니다. Model-not-found 오류는 Model Configurations와 카탈로그 사이의 id 불일치입니다. 생성은 되지만 문서를 무시하는 답변은 LLM 프로바이더보다 상위에 있는 검색이나 커넥터 문제입니다. 채팅이 흐르기 시작하면 APIsRouter 콘솔에서 요청별 모델, 토큰 수, 지출을 볼 수 있습니다. 모든 질문이 검색된 컨텍스트를 싣는 워크스페이스 도구의 경우 그 질문당 토큰 숫자가 용량 계획의 정직한 기준이며, 워크스페이스당 키 하나가 사용량 로그를 부서 레벨의 비용 리포트로 바꿔줍니다.

자주 묻는 질문