Cherry Studio에 GPT 및 외부 API 연결하기
올바른 프로토콜을 선택하고, 공급자 루트 URL을 입력하고, 정확한 모델 ID를 추가하고, 설정을 확장하기 전에 작은 요청 하나를 확인하세요.
GPT를 Cherry Studio에 연결하는 방법을 검색하면 일반적으로 기능 둘러보기가 아니라 작동하는 공급자 구성이 필요하다는 의미입니다. 중요한 필드는 프로토콜, API 키, 기본 URL 및 정확한 모델 ID입니다.
짧은 경로는 다음과 같습니다.
설정 → 모델 서비스 → 공급자 선택 또는 추가 → 자격 증명 및 API URL 입력 → 모델 가져오기 또는 추가 → 공급자 활성화 → 상태 확인 실행.
Cherry Studio에는 OpenAI, Anthropic, Google Gemini, DeepSeek, Moonshot, Ollama 및 LM Studio와 같은 서비스 제공자가 내장되어 있습니다. 게이트웨이 또는 자체 호스팅 서비스는 OpenAI 호환, Anthropic 또는 Gemini 엔드포인트를 노출하는 경우 사용자 지정 공급자를 통해 추가할 수 있습니다. 현재 UI 이름은 공식 공급자 설정 가이드를 참조하세요.
Cherry Studio를 열기 전에 필요한 것
사용하려는 서비스에서 네 가지 값을 준비합니다.
| 가치 | 의미 |
|---|---|
| 프로토콜 | OpenAI 호환, Anthropic 메시지, Gemini 또는 공급자의 문서화된 형식 |
| API 키 | 요청을 인증하는 데 사용되는 자격 증명 |
| Base URL | 공급자가 명시적으로 전체 엔드포인트를 요구하지 않는 한 루트 API 주소 |
| Model ID | 업스트림 API에서 허용되는 정확한 문자열 |
웹 채팅 비밀번호를 API 키로 사용하지 마십시오. ChatGPT 구독, API 계정 및 타사 게이트웨이는 별도의 액세스 경로입니다. 선택한 서비스에 의해 문서화된 자격 증명과 엔드포인트를 사용하세요.
5단계로 GPT 연결
1. 개방형 모델 서비스
Cherry Studio를 시작하고 설정 → 모델 서비스를 엽니다. OpenAI에 직접 전화할 때 내장된 OpenAI 공급자를 선택하세요. 게이트웨이, 애그리게이터 또는 개인 배포의 경우 공급자 추가를 선택하고 별도의 사용자 지정 항목을 만듭니다.
공급자는 모델 이름에 있는 GPT라는 단어가 아닌 프로토콜에 의해 선택됩니다. Anthropic 호환 게이트웨이 뒤의 GPT 라벨 모델에는 여전히 Anthropic 프로토콜 프로필이 필요합니다.
2. 공급자 필드 채우기
각 필드에 대해 공급자의 설명서를 사용하십시오.
| Cherry Studio 필드 | 무엇을 입력해야 할까요? | 피하다 |
|---|---|---|
| 제공자 이름 | 나중에 알아볼 라벨 | 관련되지 않은 엔드포인트에 하나의 라벨 재사용 |
| API 키 | 키 값만 | 추가 공백, 따옴표 또는 Bearer |
| API 유형 | 엔드포인트가 실제로 구현하는 프로토콜 | 모델의 마케팅 이름으로 추측 |
| API 주소 | 문서화된 루트 URL 또는 필수 전체 URL | 대시보드 URL 또는 중복된 경로 |
일반적인 OpenAI 호환 서비스에서는 Cherry Studio가 루트 주소에 버전과 요청 경로를 추가합니다. 공급자가 https://api.example.com 및 https://api.example.com/v1/chat/completions, 두 주소를 모두 안내한다면 보통 Base URL은 첫 번째 값입니다. /v1를 중복하지 말고 공급자가 명시한 경우에만 전체 경로를 사용하세요.
사용자 정의 공급자 가이드는 추가 엔드포인트, 수동 모델 입력 및 vLLM 스타일 로컬 서비스를 다룹니다.
3. 모델 가져오기 또는 추가
모델 목록 가져오기를 클릭합니다. 엔드포인트가 모델 검색을 노출하는 경우 + 버튼을 사용하여 모델을 추가하세요. 반환된 ID는 신뢰할 수 있습니다. 날짜, 공급업체 접두사, 하이픈, 버전 접미사를 표시된 대로 정확하게 유지하세요.
공급자가 모델 목록을 공개하지 않는 경우 모델을 수동으로 추가하세요. 공급자가 성공적으로 저장되었다고 해서 자동으로 채팅 선택기에서 모델을 사용할 수 있게 되는 것은 아닙니다. 모델을 추가하고 공급자 스위치를 활성화해야 합니다.
4. 짧은 요청 하나를 확인하세요.
방금 추가한 모델에 확인을 사용한 다음 최소한의 프롬프트를 보냅니다.
Reply with exactly: connection successful
이는 인증 및 라우팅 문제를 비전, 도구, 장기 컨텍스트 또는 에이전트 기능 문제와 분리합니다. 통화가 가능한 경우 공급자의 사용 페이지에서 통화를 확인하세요.
5. 한 번에 하나씩 고급 기능 추가
일반 텍스트가 작동한 후 스트리밍, 이미지, 도구 또는 추론 매개변수를 하나씩 테스트합니다. 성공적인 채팅 응답은 기본 텍스트 경로가 작동한다는 것만 증명합니다. 모델이나 프로토콜이 Cherry Studio가 노출하는 모든 기능을 지원한다는 것을 증명하지는 않습니다.
다른 타사 API 연결
OpenAI 호환 게이트웨이
게이트웨이가 OpenAI Chat Completions 또는 다른 OpenAI 호환 표면을 문서화하는 경우 사용자 지정 공급자 → OpenAI를 사용하세요. 이는 집계자, 개인 게이트웨이, vLLM 및 많은 호스팅 개방형 모델의 일반적인 경로입니다.
다중 프로토콜 게이트웨이
새로운API 스타일 게이트웨이는 하나의 루트 주소에서 OpenAI 채팅, OpenAI 응답, Anthropic 메시지 및 Gemini 경로를 노출할 수 있습니다. Cherry Studio의 NewAPI 지침는 클라이언트가 선택한 프로토콜에 대한 버전 경로를 선택한다고 설명합니다. 게이트웨이가 해당 계약을 따르는 경우 NewAPI 사전 설정을 사용하십시오. 문서화된 경로나 모델 검색 변형이 있는 경우 사용자 지정 공급자를 사용합니다.
올라마, LM 스튜디오, vLLM
일치하는 로컬 공급자를 선택하거나 로컬 서버가 OpenAI 호환 API를 노출하는 경우 사용자 지정 OpenAI 공급자를 사용합니다. 로컬 서버에서 실제로 로드한 모델명을 입력하세요. 로컬 실행은 데이터 노출을 줄일 수 있지만 로컬 모델은 비전, 도구, 컨텍스트 길이 및 추론 지원에서 여전히 다릅니다.
모델 목록이 비어 있는 경우
다음 검사를 순서대로 진행하세요.
- 서비스가 모델 목록 엔드포인트를 구현하는지 확인합니다. 일부 API는 수동으로 제공한 모델 ID만 허용합니다.
- 중복된 경로 세그먼트를 제거합니다. Cherry Studio가 다른
/v1를 추가하면 이미/v1가 포함된 루트 URL이 실패할 수 있습니다. - 공급자의 관리 대시보드 주소가 아닌 API 주소를 사용했는지 확인하세요.
- 공급자가 반환한 정확한 모델 ID를 복사하세요. 표시 이름과 API ID는 서로 바꿔서 사용할 수 없습니다.
- 공급자가 활성화되어 있는지 확인하십시오. 비활성화된 공급자는 선택기에서 해당 모델을 숨깁니다.
일반적인 오류
| 오류 | 가능한 원인 | 첫 번째 확인 |
|---|---|---|
401 Unauthorized | 유효하지 않거나 만료되었거나 형식이 잘못된 키 | 키를 다시 복사하고 프로토콜 프로필을 확인하세요. |
403 Forbidden | 계정, 프로젝트, 잔액 또는 키 한도 | 공급자 권한 및 할당량 확인 |
404 Not Found | 잘못된 루트 URL, 중복된 버전 경로 또는 프로토콜 불일치 | 문서화된 기본 URL 복원 |
400 Bad Request | 지원되지 않는 매개변수 또는 요청 형태 | 맞춤 매개변수를 삭제하고 일반 텍스트를 다시 시도하세요. |
model not found | Cherry Studio에 잘못된 ID 또는 모델이 추가되지 않았습니다. | 정확한 업스트림 모델 ID를 복사하세요. |
| 텍스트는 작동하지만 이미지/도구는 작동하지 않습니다. | 모델이나 프로토콜에 해당 기능이 부족함 | 기능 목록 및 경로 확인 |
| 시간 초과 | 공급자 지연 시간, 네트워크 문제 또는 과도한 요청 | 짧은 프롬프트와 하나의 모델을 사용하여 다시 시도하세요. |
한 번에 하나의 변수를 변경하십시오. 하나의 공급자, 하나의 모델, 하나의 간단한 요청으로 시작하세요. 그런 다음 여러 모델이나 도구를 추가하세요.
여러 모델 비교
Cherry Studio를 사용하면 대화 선택기에서 모델을 전환하고 선택한 여러 모델에 동일한 프롬프트를 보낼 수 있습니다. 각 선택은 독립적인 요청을 생성합니다. 비교에는 유용하지만 자동 투표나 품질 보장은 아닙니다. 선택한 모델마다 요청 수, 비용 및 데이터 노출이 증가합니다. 공식 비교 가이드에서는 단순히 어떤 답변이 '가장 좋은지' 묻는 대신 명시적인 평가 기준을 작성할 것을 권장합니다.
OmniaKey를 하나의 공급자로 사용
GPT, Claude, Gemini 및 기타 모델에 대해 별도의 진입점을 유지하지 않으려면 Cherry Studio에서 OmniaKey를 사용자 지정 OpenAI 호환 공급자로 구성하세요.
- 전용 OmniaKey API 키를 생성하고 API 키 페이지에서 적절한 키 제한을 설정하세요.
- Cherry Studio에서 설정 → 모델 서비스 → 공급자 추가를 엽니다.
- OpenAI 호환 유형을 선택하고 OmniaKey 빠른 시작에서 기본 URL과 키를 입력하세요.
- 모델 목록을 가져오거나 라이브 모델 카탈로그에서 정확한 ID를 추가하세요.
- 공급자를 활성화하고 간단한 검사를 실행한 후 사용에서 요청을 확인하세요.
현재 OmniaKey 카탈로그에는 추가 모델 제품군과 함께 Claude, GPT, Gemini 및 Grok가 포함되어 있습니다. ID와 기능은 동적이므로 이전 튜토리얼보다는 라이브 카탈로그를 사용하세요. OpenAI 호환 경로가 모든 공급자별 기능을 동일하게 만드는 것은 아닙니다. 비전이나 도구를 활성화하기 전에 모델 및 프로토콜 기능을 확인하십시오.
FAQ
Cherry Studio는 제가 찾은 API를 사용할 수 있나요?
서비스가 Cherry Studio가 지원하는 프로토콜을 노출하는 경우에만. 문서화된 요청 형식, 인증 방법, 모델 ID가 없는 임의의 URL로는 충분하지 않습니다.
루트 URL을 입력해야 합니까, 아니면 /chat/completions를 입력해야 합니까?
공급자 설명서를 따르십시오. 기존 공급자는 일반적으로 루트 URL을 사용하고 Cherry Studio가 요청 경로를 추가하도록 합니다. 공급자가 명시적으로 요구하는 경우에만 전체 엔드포인트를 사용하세요.
채팅은 가능하지만 도구나 이미지를 사용할 수 없는 이유는 무엇입니까?
기본 텍스트 성공은 선택한 모델, 프로토콜 및 클라이언트 경로가 도구 또는 비전을 지원한다는 것을 증명하지 않습니다. 각 기능을 별도로 확인하세요.
ChatGPT 웹 구독은 API 키입니까?
아니요. Cherry Studio에는 공급자 API 자격 증명 또는 호환 가능한 게이트웨이 자격 증명이 필요합니다. 웹 로그인 세부 정보를 API 키 필드에 붙여넣어서는 안 됩니다.
소스와 신선도
이 가이드에서는 Cherry Studio의 현재 공급자, 사용자 지정 공급자, OpenAI, NewAPI 및 다중 모델 문서와 OmniaKey의 현재 API 및 모델 문서를 사용합니다. 모델 ID, 공급자 기능 및 경로와 같은 기술 값은 변경될 수 있습니다. 구성 시 이를 확인하십시오.