API에서 OpenAI 호환이란?

짧은 답변

제공업체가 API가 openai-compatible하다고 할 때, OpenAI 클라이언트 라이브러리가 보내는 것과 동일한 HTTP 요청을 수락하고 동일한 구조의 응답을 반환한다는 의미입니다. 코드를 유지하고 base URL과 키만 변경하면 호출이 다른 서버로 전달됩니다.

그것이 전체 약속입니다. 이는 두 충전기가 같은 플러그를 사용한다고 말하는 것과 같은 인터페이스에 대한 진술입니다. 케이블의 다른 끝에 무엇이 있는지 알려주지 않습니다. 모델, 안전 규칙, 가격 및 제한은 모두 제공업체가 결정하며 크게 다릅니다.

레이블이 실제로 포함하는 내용

실제로 OpenAI 호환성은 구체적인 항목의 짧은 목록입니다. 제공업체가 모두 지원하면 대부분의 클라이언트 코드가 변경 없이 실행됩니다.

• 경로들. 채팅 요청은 POST /v1/chat/completions로 전송되며, 모델 목록은 GET /v1/models에서 가져옵니다.
• 인증. 키는 Authorization: Bearer 헤더에 포함되어 전송됩니다.
• 요청 본문. model 문자열, role 및 content이 있는 개체의 messages 배열, 그리고 temperature, top_p, stop 및 seed과 같은 선택적 샘플링 필드입니다.
• 응답 본문. 어시스턴트 메시지가 있는 choices 배열, finish_reason 및 토큰 수가 있는 usage 개체입니다.
• 스트리밍. stream: true를 사용하면 서버는 작은 JSON 델타를 각각 담고 있는 서버 전송 이벤트를 보내며, 최종 마커로 끝납니다.
• 선택적 기능. 도구 호출, JSON 모드 및 제공업체가 지원하기로 선택한 유사한 필드입니다.

이 형식을 대상으로 한 도구가 많아 공통 목표가 되었습니다. 편집기, 에이전트 프레임워크, 역할극 프론트엔드 및 일반 스크립트는 모두 사용자 정의 Base URL을 입력할 수 있으며 이것이 전부입니다.

왜 하나의 형식이 공통 목표가 되었습니까

채팅 완료 형식은 단순하고 초기에 도착했기 때문에 퍼졌습니다. 이를 지원하는 도구 작성자는 한 번 지원하면 많은 백엔드에 도달할 수 있고, 이를 지원하는 백엔드 작성자는 한 번 지원하면 많은 도구에 도달할 수 있습니다. 이는 양측 모두에게 좋은 거래이므로 형식이 정착되었습니다. 이를 설계한 회사와 관련이 없는 서비스 중에서도 그렇습니다.

개발자로서 이는 실용적인 의미를 가집니다. 모든 공급자에 대해 다른 통합 코드를 작성할 필요가 없습니다. 오후 한 시간 안에 엔드포인트 간에 프로토타입을 이동하거나, 동일한 프롬프트로 두 모델을 비교하거나, 첫 번째 공급자가 느릴 때 두 번째 공급자를 대체로 유지할 수 있습니다. 방향을 바꾸는 비용이 낮기 때문에 새로운 서비스를 확약 없이 시도하기가 더 쉬워집니다.

반면 공통 인터페이스는 실제 차이를 숨깁니다. 전환이 매우 쉽기 때문에 URL 뒤의 모든 것이 동일하다고 가정하기 쉽습니다. 하지만 그렇지 않으며, 아래 섹션에서 일반적으로 격차가 발생하는 부분을 확인할 수 있습니다.

레이블이 알려주지 않는 것

여기서 사람들이 놀라게 됩니다. 이 레이블은 API가 귀하의 작업에 유용한지 여부를 결정하는 모든 것을 생략합니다.

뒤의 모델

호환 가능한 엔드포인트는 어떤 모델이든 처리할 수 있습니다. 일부는 오픈 웨이트 모델을 처리하고, 일부는 여러 벤더로 라우팅하며, 일부는 독점 모델을 래핑합니다. 호환성은 서비스가 OpenAI에서 실행된다는 의미도, 모델이 그들의 모델처럼 동작한다는 의미도 아닙니다. model에 전달하는 모델 이름은 제공업체가 정의한 문자열일 뿐입니다.

거절 동작

콘텐츠 규칙은 모델과 제공업체의 것이며 프로토콜이 아닙니다. 두 호환 API는 동일한 프롬프트에 반대 방식으로 답변할 수 있습니다. 사용 사례가 소설, 역할극 또는 기타 합법적인 성인 콘텐츠인 경우 연결하기 전에 제공업체의 거절에 대해 확인하세요.

기능 깊이

일부 공급자는 채팅 기능만 구현합니다. 다른 공급자는 도구, JSON 모드, 로그 확률 또는 추가 엔드포인트를 추가합니다. 서버가 무시하는 필드를 전송하는 클라이언트는 항상 큰 오류를 발생하지 않으므로, 조용한 불일치가 발생할 수 있습니다.

제한, 가격 및 오류

속도 제한, 컨텍스트 길이, 최대 본문 크기 및 토큰당 가격은 모두 제공업체 선택입니다. HTTP 상태 코드가 일치하더라도 오류 본문도 세부 사항이 다르므로 재시도 로직은 메시지 텍스트가 아닌 상태 코드 및 헤더에 기반해야 합니다.

빠른 호환성 테스트

제공업체는 세 가지 요청으로 몇 분 안에 확인할 수 있습니다. 키를 자신의 것으로 바꿉니다. 이 예시는 이 사이트의 base URL을 사용합니다.

Copycurl https://api.kimicode.top/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

첫 번째 호출은 키를 확인하고 모델 ID를 나열합니다. 두 번째는 채팅 구조를 확인합니다. 그런 다음 애플리케이션에 의존하는 부분을 테스트합니다: "stream": true를 추가하고 증분 청크를 관찰하며, 함수 호출을 사용하는 경우 tools 배열을 전달하고, 구문 분석 가능한 출력이 필요한 경우 response_format을 {"type":"json_object"}로 설정합니다.

또한 의도적으로 오류를 발생시켜 보세요. 예를 들어 잘못된 키를 사용하는 경우입니다. 클라이언트가 처리할 수 있는 표준 HTTP 상태 코드와 JSON 오류 본문이 표시되어야 합니다.

Node에서의 동일한 호출

JavaScript SDK도 동일한 두 값을 사용합니다. 다음은 대부분의 채팅 인터페이스에서 사용하는 형태의 스트리밍 호출입니다.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.kimicode.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Name three uses of SSE." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

이것이 단어를 하나씩 출력한다면 스트리밍 경로가 끝까지 작동하는 것입니다. 이 루프는 호환되는 모든 제공업체에서 작동하며, 이것이 포맷의 핵심 목적입니다.

코드에서 전환이 어떻게 보이는지

공식 Python SDK를 사용하면 변경 사항은 두 가지 생성자 인수입니다. 프로그램의 나머지는 그대로 유지됩니다.

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.kimicode.top/v1",
    api_key="YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarize SSE in one sentence."}],
)
print(resp.choices[0].message.content)

Node SDK도 동일한 개념으로, baseURL 및 apiKey 옵션을 사용합니다. 많은 도구는 환경 변수에서 OPENAI_BASE_URL 및 OPENAI_API_KEY을 읽으므로, 코드를 수정하지 않고도 전환할 수 있는 경우가 있습니다.

모델 문자열도 변경하는 것을 잊지 마세요. 새 서버가 호스팅하지 않는 모델을 이름으로 지정하는 요청은 실패하며, 이것이 가장 일반적인 첫 번째 오류입니다.

이 사이트의 API가 어디에 해당하는지

이 서비스는 OpenAI 형식을 따르는 호스팅된 텍스트 전용 API입니다. 독립 운영 제공업체가 운영하며 합법적인 성인 사용에 대한 콘텐츠 거부 없이 답변하도록 튜닝된 단일 오픈 웨이트 모델을 실행합니다. 이 서비스는 어떤 모델 벤더의 공식 API가 아니며, 벤더 간 라우팅도 수행하지 않습니다. 모델 ID는 uncensored입니다.

SSE를 통한 스트리밍, 종료 시 사용량 보고, 함수 호출, JSON 모드를 지원하며, temperature, top_p, stop, seed 및 페널티를 전달합니다. 컨텍스트 창은 프롬프트와 생성된 응답을 합쳐 100,000 토큰입니다. 이미지나 오디오를 생성하지 않으며, 임베딩이나 파인튜닝도 제공하지 않습니다. 하나의 규칙은 고정되어 있습니다: 미성년자가 포함된 성적인 콘텐츠는 금지됩니다.

청구는 선불 크레딧 기반이며 사용량에 따라 과금됩니다: 입력 토큰 1M당 $0.15, 출력 토큰 1M당 $0.50이며 구독은 없습니다. 가격 페이지에서 수치를 확인할 수 있으며, 문서에서 첫 번째 요청 방법을 안내합니다. 비용을 지불하지 않고 사용해 보고 싶다면, 새 계정은 API 키 페이지에서 한 번의 클릭으로 $0.50 무료 체험 크레딧을 받을 수 있습니다.

호환성 문제의 흔한 함정

1. 잘못된 base URL입니다. URL은 /v1에서 끝나야 합니다. 클라이언트는 /chat/completions을 자체적으로 붙이므로, base URL에 추가하면 404 오류가 발생합니다.
2. 지원되지 않는 매개변수. 라이브러리가 서버가 알 수 없는 필드를 보내면, 해당 필드가 거부되는지 아니면 무시되어 삭제되는지 확인한 후 제거하세요.
3. 스트리밍과 동시성. 스트리밍 요청은 스트림이 종료될 때까지 동시성 슬롯을 점유합니다. 앱에서 많은 스트림을 열면 분당 요청 수가 낮더라도 concurrency 코드와 함께 429 오류를 받을 수 있습니다.
4. 429 발생 시 재시도. 429 응답은 대기하라는 신호로 처리하십시오. Retry-After 헤더가 있는 경우 이를 준수하십시오.
5. 토큰 계산. 다른 제공업체의 토크나이저가 일치한다고 가정하지 마세요. 청구 대상 숫자는 응답의 usage 객체에서 확인하세요.

이러한 문제들은 어디에서 찾아야 하는지 알면 수정하기 어렵지 않으며, 대부분 첫 번째 오류 메시지를 주의 깊게 읽는 것으로 해결됩니다.

더 많은 가이드

• OpenAI 호환 API로 OpenCode 사용법: 설정
• Kimicode 대체재: 무검열 호스팅 LLM API
• 무검열 LLM API: OpenAI 호환 통합 및 가격