사용자 정의 공급자를 사용하면 PandaNpc가 사용자가 제어하는 API 계정, 프라이빗 게이트웨이 또는 로컬 모델 엔드포인트를 사용할 수 있습니다. 이를 일반적으로 BYOK(Bring Your Own Key)라고 합니다. 내장 카탈로그 외부의 모델, 공급자 측 청구, 내부 프록시, Ollama, LM Studio 또는 자체 호스팅 OpenAI 호환 서비스가 필요할 때 유용합니다.
지원되는 직접 채팅의 경우 PandaNpc는 내장 모델을 대체하지 않고 구성된 엔드포인트로 요청을 보냅니다. 업스트림 공급자가 가격, 보존, 속도 제한, 모델 가용성 및 허용 사용을 계속 제어합니다.
사전 요구 사항 및 보안 경계
공급자를 추가하기 전에 다음을 준비하십시오:
- 공급자의 API key 또는 로컬 인증 토큰.
- OpenAI 호환 서비스의 경우 일반적으로
/v1로 끝나는 API 기본 URL. - API에서 허용하는 정확한 모델 식별자.
- 기본값을 재정의하려는 경우 문서화된 컨텍스트 창 및 최대 출력 제한.
최소한의 권한과 공급자가 지원하는 경우 지출 한도가 있는 전용 키를 사용하십시오. 키를 문서, 채팅 프롬프트, 스크린샷, 브라우저 콘솔 출력 또는 Git 저장소에 절대 넣지 마십시오.
웹 브라우저에서 직접 요청은 CORS의 적용을 받습니다. 공급자는 https://pandanpc.com에서의 요청을 허용해야 합니다. http://localhost:11434/v1와 같은 기본 URL은 원격 PandaPaw 머신이 아니라 브라우저를 실행하는 컴퓨터를 가리킵니다. 데스크톱 앱은 브라우저 CORS에 같은 방식으로 제한되지 않으므로 로컬 엔드포인트에 더 적합할 수 있습니다.
1단계: 모델 구성 열기
PandaNpc에 로그인하고 모델 구성을 엽니다. 공급자와 모델은 별도의 레코드입니다. 공급자는 연결 및 인증 세부 정보를 저장하고, 각 모델은 해당 연결로 전송되는 식별자와 한도를 저장합니다.
공식 공급자가 이미 표시되어 있으면 다른 프로토콜을 만들지 말고 해당 공급자를 구성하거나 복사하십시오. 새로운 OpenAI 호환 게이트웨이의 경우 공급자 추가를 선택하십시오.
2단계: 공급자 추가
공급자 양식을 작성하십시오:
| 필드 | 입력 내용 | 예시 또는 안내 |
|---|---|---|
| 표시 이름 | 사용자에게 표시되는 레이블 | Company AI Gateway |
| 공급자 ID | 안정적인 내부 식별자 | company-openai |
| API Key | 베어러 토큰으로 사용되는 비밀 | 공급자가 발급한 값 |
| 기본 URL | /chat/completions가 없는 API 루트 |
https://gateway.example.com/v1 |
| 프로토콜 | 업스트림 API 형식 | OpenAI 호환 채팅 완성에는 openai 선택 |
| 비밀 | 선택적 두 번째 비밀 | 공급자가 요구하지 않으면 비워 둠 |
| 조직 | 선택적 조직 식별자 | 공급자가 요구하는 경우에만 |
| 프로젝트 | 선택적 프로젝트 식별자 | 공급자가 요구하는 경우에만 |
| 콘텐츠 배열 지원 | 메시지 콘텐츠가 구조화된 배열을 사용할 수 있는지 여부 | 최신 다중 모달 메시지 콘텐츠를 허용하는 공급자에 대해 활성화 유지 |
PandaNpc는 기본 URL에서 후행 슬래시를 제거하고 직접 OpenAI 호환 채팅 요청을 위해 /chat/completions를 추가합니다. 따라서 다음을 입력하십시오:
https://api.example.com/v1다음이 아니라:
https://api.example.com/v1/chat/completions모델을 추가하기 전에 공급자를 저장하십시오. 기존 공급자를 편집할 때 API Key 또는 비밀 필드가 비어 있으면 "구성된 값을 유지"를 의미합니다. 저장된 비밀을 양식으로 다시 노출하지 않습니다.
3단계: 모델 추가
공급자 아래에서 모델 추가를 선택하고 다음 필드를 작성하십시오:
| 필드 | 의미 | 예시 |
|---|---|---|
| 표시 이름 | 사람이 읽을 수 있는 선택 레이블 | My Coding Model |
| 모델 값 | 정확한 업스트림 모델 ID | model-name-from-provider |
| 모델 유형 | PandaNpc 기능/카테고리 매핑 | 양식에서 현재 값 선택 |
| 공급자 | 위에서 생성한 공급자 레코드 | Company AI Gateway |
| 컨텍스트 창 | 지원되는 총 토큰 수 | 공급자의 문서화된 정수 제한 사용 |
| 최대 토큰 | 생성되는 최대 출력 토큰 수 | 공급자 제한보다 크지 않은 양수 값 사용 |
표시 이름은 API 호출에 영향을 주지 않고 변경할 수 있습니다. 모델 값은 마케팅 이름으로 추측할 수 없습니다. 공급자의 API 문서 또는 모델 목록 엔드포인트에서 복사하십시오.
확실하지 않으면 컨텍스트 창과 최대 토큰을 비워 두십시오. 서버가 지원하는 것보다 큰 컨텍스트 창을 선언하는 것보다 보수적인 기본값이 더 안전합니다. 이러한 필드는 PandaCode에서 특히 중요합니다. 압축 및 출력 예산에 영향을 주기 때문입니다.
일반적인 엔드포인트 예시
다음 패턴은 URL 형태를 보여줍니다. 가용성과 모델 ID는 설치 또는 공급자 계정에 따라 다릅니다:
| 서비스 유형 | 일반적인 기본 URL | 참고 사항 |
|---|---|---|
| OpenAI 호환 클라우드 API | https://provider.example.com/v1 |
스트리밍 Chat Completions 및 베어러 인증 지원 필요 |
| 보기 컴퓨터의 Ollama | http://localhost:11434/v1 |
Ollama의 OpenAI 호환 엔드포인트 시작, 브라우저 사용 시 CORS 구성 필요할 수 있음 |
| 보기 컴퓨터의 LM Studio | http://localhost:1234/v1 |
로컬 서버 시작 및 로드된 모델 ID 선택 |
| 사설 네트워크 게이트웨이 | https://ai.internal.example/v1 |
PandaNpc 클라이언트가 호스트를 확인하고 연결할 수 있어야 함 |
"OpenAI 호환"을 광고하는 모든 서비스가 스트리밍, 도구 호출, 이미지, 추론 필드 또는 동일한 오류 응답을 구현한다고 가정하지 마십시오. 워크플로에 필요한 정확한 기능을 테스트하십시오.
공급자 및 모델 확인
구성에 의존하기 전에 저비용, 비민감 프롬프트를 사용하십시오:
- 새 대화에서 새 모델을 선택하십시오.
Reply with exactly: provider connected를 보내십시오.- 응답이 스트리밍되고 공급자 대시보드에 요청이 기록되는지 확인하십시오.
- 짧은 후속 메시지를 보내 대화 기록을 확인하십시오.
- 도구, 이미지 또는 긴 컨텍스트가 필요하면 각 기능을 별도로 테스트하십시오.
로컬 엔드포인트의 경우 PandaNpc 외부에서 먼저 확인하십시오. OpenAI 호환 모델 목록은 종종 다음으로 확인할 수 있습니다:
curl http://localhost:11434/v1/models응답은 연결 가능성과 모델 ID를 확인하는 데만 사용하십시오. 프로덕션 API key를 셸 기록에 직접 넣지 마십시오.
PandaCode와 함께 사용자 정의 모델 사용
PandaCode는 DeepSeek, Qwen, OpenAI 호환 게이트웨이 또는 내부 서비스를 포함하여 선택한 모델 백엔드를 사용하면서 Claude Code 스타일의 코딩 워크플로를 제공할 수 있습니다. 공급자와 모델을 구성한 후 관련 PandaCode 연결 또는 작업에 해당 모델을 선택하십시오.
모델은 코딩 엔진이 요구하는 상호 작용 패턴을 지원해야 합니다. 일반 채팅에서 작동하는 공급자는 도구 호출, 장기 실행 스트림 또는 구조화된 콘텐츠에서 실패할 수 있습니다. 채팅 모델과 로컬 코딩 엔진의 차이점은 PandaNpc가 지원하는 AI 모델을 참조하고, 원격 엔진 설정은 PandaPaw 설치 및 명령어를 참조하십시오.
문제 해결
`401` 또는 `403` 인증 오류
새 공급자 키를 만들고 활성 상태인지 확인한 후 다시 입력하십시오. 업스트림 서비스가 조직, 프로젝트 또는 다른 인증 방법을 요구하는지 확인하십시오. 편집 화면에서 복사한 마스킹된 키는 원래 비밀이 아닙니다.
`404` 엔드포인트 또는 모델을 찾을 수 없음
PandaNpc가 추가하므로 구성된 기본 URL에서 /chat/completions를 제거하십시오. 필요한 경우 /v1이 있는지 확인하고 모델 값이 업스트림 모델 ID와 정확히 일치하는지 확인하십시오. 공급자는 잘못된 URL과 사용할 수 없는 모델 모두에 대해 동일한 404를 반환할 수 있습니다.
브라우저가 네트워크 또는 CORS 오류 보고
브라우저 개발자 콘솔은 차단된 출처를 식별하는 목적으로만 열고 비밀을 붙여넣지 마십시오. 공급자가 https://pandanpc.com을 허용하도록 구성하고 HTTPS 엔드포인트를 사용하거나 PandaNpc 데스크톱 앱을 사용하십시오. 혼합 콘텐츠 규칙은 HTTPS 페이지가 일부 일반 HTTP 엔드포인트를 호출하지 못하게 차단합니다.
로컬 Ollama 또는 LM Studio에 연결할 수 없음
서버가 요청하는 클라이언트와 같은 컴퓨터에서 실행 중이고 구성된 인터페이스와 포트에서 수신 중인지 확인하십시오. 모델 서버가 다른 컴퓨터에서 실행 중이면 localhost는 잘못된 것입니다. 연결 가능한 사설 호스트 이름 또는 IP를 사용하고 서비스를 노출하기 전에 보안을 설정하십시오.
응답이 시작되지만 중지되거나 콘텐츠가 없음
API가 스트리밍 Chat Completions를 지원하고 표준 data: 이벤트를 내보내는지 확인하십시오. 최대 토큰을 줄이고 텍스트 전용 메시지를 테스트하며 공급자가 문자열 콘텐츠만 허용한다고 문서화한 경우에만 구조화된 콘텐츠 배열을 비활성화하십시오.
긴 세션이 컨텍스트 한도 근처에서 실패
구성된 컨텍스트 창을 공급자의 실제 지원 한도로 낮추고 출력, 시스템 지침 및 도구 결과를 위한 공간을 확보하십시오. 모델 구성을 변경한 후 새 세션을 시작하여 새 한도가 일관되게 적용되도록 하십시오.
계정 수준 할당량 및 데이터 흐름에 대한 자세한 내용은 PandaNpc 계정, 요금제 및 API 비용 및 개인정보 처리방침을 읽으십시오.