GLM API의 연동 비용은 많은 사람이 생각하는 것보다 낮습니다. OpenAI 호환 인터페이스를 제공하므로 기존 OpenAI SDK에서는 보통 API 키, Base URL, 모델명 세 곳만 바꾸면 됩니다. 진짜 함정은 "호출이 되는가"가 아니라 모델명이 유효한지, 스트리밍 출력을 어떻게 처리하는지, 도구 호출이 어떤 형식으로 반환되는지, OpenAI에서 이전할 때 어떤 파라미터를 그대로 가져오면 안 되는지입니다.

이 글은 최소 요청으로 경로를 실행한 뒤 스트리밍, 도구 호출, 오류 해결, 이전 체크리스트를 보충합니다. 모든 예시는 키만 교체하면 바로 실행할 수 있습니다.

안내: 즈푸(Zhipu), GLM, BigModel은 관련 권리자의 상표이며 이 글은 기술 설명만 제공합니다. 즈푸와 소속, 대리, 인증 관계가 없습니다. Base URL, 모델명, 컨텍스트 길이, 과금 기준은 조정될 수 있으므로 즈푸 오픈 플랫폼 공식 문서와 사이트 내 모델 가격을 기준으로 하세요.

1. 연동 전 준비

시작 전에 세 가지를 확인하세요.

  • 사용 가능한 API 키가 있고 그 유형이 호출할 인터페이스와 맞는지.
  • 올바른 Base URL이 있고 공식 직접 연결과 게이트웨이 주소를 섞지 않았는지.
  • 현재 실제로 사용 가능한 모델명이 있고 오래된 글의 예시를 그대로 복사하지 않았는지.

신규 프로젝트라면 먼저 curl로 인증과 네트워크를 검증한 뒤 SDK를 연동하세요. 그래야 오류가 났을 때 키, 주소, 코드 중 어디가 문제인지 판단하기 쉽습니다.

2. Base URL 작성법

즈푸 공식 OpenAI 호환 인터페이스의 Base URL은 보통 다음과 같습니다.

https://open.bigmodel.cn/api/paas/v4

ZSQH AI 게이트웨이의 OpenAI 호환 주소는 다음과 같습니다.

https://ai.zhongshangqihang.com/v1

둘 다 OpenAI의 /chat/completions 경로를 붙여 사용합니다. 코드에서 버전 세그먼트나 /chat/completions를 중복으로 붙이지 말고, 끝에 슬래시를 임의로 더하거나 빼서 섞지 마세요.

연동 방식 Base URL 예시 적용 시나리오 주의
즈푸 공식 https://open.bigmodel.cn/api/paas/v4 GLM만 사용, 최신 기능 필요 공식 계정과 잔액 필요
ZSQH AI 게이트웨이 https://ai.zhongshangqihang.com/v1 멀티모델 통합 진입점, 통합 청구 게이트웨이에서 키 생성 필요

3. 모델명 선택

GLM 시리즈는 능력에 따라 텍스트, 비전, 음성, 임베딩 등으로 나뉩니다. 텍스트 모델에도 등급이 있어 어떤 모델은 범용 대화와 Agent에, 어떤 모델은 저지연·고동시성에, 어떤 모델은 더 긴 컨텍스트에 맞습니다. 공식 문서에 현재 나온 GLM-5 시리즈를 예로 들면 glm-5.3, glm-5.3-flash, glm-5.2 같은 표기가 흔하지만 모델은 계속 갱신되므로 실제 사용 가능한 이름은 콘솔과 모델 가격 페이지를 기준으로 하세요.

선정할 때 "가장 강한" 모델만 보지 마세요. 고객지원 질의응답, 대량 분류 같은 작업은 저지연 등급이 더 경제적인 경우가 많고 장문 문서 분석과 복잡한 Agent에 상위 등급을 씁니다. 모델명을 코드에 하드코딩하지 말고 설정 항목으로 만들면 이후 전환이 훨씬 쉬워집니다.

작업에 이미지 이해가 포함되면 비전 입력을 지원하는 모델을, 벡터 검색이 포함되면 embedding 시리즈를 선택하세요. 텍스트, 비전, 임베딩 모델은 인터페이스 경로와 파라미터가 완전히 같지 않으므로 하나의 요청 본문을 그대로 적용하면 안 됩니다. 출시 전에 후보 모델을 같은 평가 세트에 넣어 정확도, 지연, 사용량을 비교한 뒤 주 모델과 대체 모델을 정하세요.

4. curl로 첫 호출 실행

먼저 환경 변수를 준비해 키가 명령 기록에 남지 않게 하세요.

export GLM_API_KEY="your_key_here"

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $GLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {"role": "system", "content": "당신은 간결한 기술 어시스턴트입니다."},
      {"role": "user", "content": "API 게이트웨이가 무엇인지 세 문장으로 설명하세요."}
    ],
    "temperature": 0.6
  }'

정상 반환 시 세 필드를 중점적으로 보세요. choices[0].message.content는 답변, usage는 이번 사용량, finish_reason은 종료 이유입니다. 401이면 키와 요청 헤더를, 1211이면 모델명을 먼저 확인하세요.

5. Python SDK 호출과 스트리밍 출력

OpenAI SDK 1.0 이상이 필요합니다. Base URL을 GLM으로 지정하면 호출 방식은 OpenAI와 거의 같습니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("GLM_API_KEY"),
    base_url="https://open.bigmodel.cn/api/paas/v4",
)

stream = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "100자 이내의 제품 소개를 작성하세요."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

스트리밍에서 주의할 점이 있습니다. 첫 chunk에는 역할 정보만 있고 content가 비어 있을 수 있으므로 모든 chunk에 텍스트가 있다고 가정하지 마세요. 사고 모드를 켜면 추론 내용이 reasoning_content 필드에 나오고 최종 답변은 여전히 content에 있으므로 둘을 분리해 처리하고 추론 과정을 최종 사용자에게 그대로 노출하지 마세요.

6. 도구 호출과 파라미터 차이

도구 호출은 OpenAI의 tools와 tool_choice 형식을 따릅니다. 모델이 message.tool_calls를 반환하면 각 호출의 function.arguments를 JSON으로 파싱해 로컬 함수를 실행하고 결과를 tool 역할 메시지로 되돌려 보내야 합니다. 운영 환경에서는 파라미터 검증과 타임아웃 제어를 해야 하며 모델이 생성한 파라미터를 그대로 신뢰하면 안 됩니다.

OpenAI에서 이전할 때 몇 가지 차이를 주의하세요. temperature 범위는 보통 0~1이고 0을 보내면 적용되지 않을 수 있습니다. 기본값은 약 0.6입니다. 일부 신규 기능은 extra_body로 파라미터를 전달해야 합니다. 구체적인 파라미터는 공식 OpenAI 호환 문서를 기준으로 하세요.

스트리밍에서는 클라이언트 연결 종료도 처리해야 합니다. 사용자가 페이지를 닫으면 서버가 업스트림 요청을 빨리 취소해 계속 생성과 과금을 막아야 합니다. 업무상 전체 생성이 반드시 필요하다면 작업을 백그라운드 대기열로 옮기고 프런트엔드 연결에 의존하지 마세요.

7. 자주 발생하는 오류 대조표

현상 가능한 원인 처리 방식
401 / 1000 키 오류, 유형 불일치 키 유형과 요청 헤더 확인
1211 모델명이 없거나 개통되지 않음 콘솔의 사용 가능 모델 확인
1261 입력이 컨텍스트 제한 초과 프롬프트 압축 또는 분할
1302 / 1305 계정 속도 제한 또는 플랫폼 혼잡 동시성 축소, 백오프 재시도
1113 계정 연체 충전 후 재시도
연결 타임아웃 DNS, 프록시, 네트워크 경로 먼저 curl로 네트워크 계층 확인

재시도는 429, 5xx, 네트워크 타임아웃에만 유효합니다. 401, 1211, 1261 같은 오류는 재시도해도 나아지지 않고 시간과 할당량만 낭비합니다.

8. OpenAI에서 이전하는 체크리스트

  1. 기존 프롬프트, 모델 파라미터, 평가 세트를 백업합니다.
  2. GLM 전용 키를 새로 만들고 다른 벤더의 키를 재사용하지 않습니다.
  3. Base URL과 모델명을 설정 항목으로 바꿉니다.
  4. 같은 샘플 세트로 출력 품질, 지연, 사용량을 비교합니다.
  5. 스트리밍 파싱, 도구 호출, JSON 출력의 호환성을 확인합니다.
  6. 재시도, 타임아웃, 동시성을 조정하고 일주일 관찰한 뒤 전면 전환합니다.

9. 자주 묻는 질문(FAQ)

1. GLM API는 OpenAI와 완전히 호환되나요?

대부분의 주요 인터페이스는 호환되지만 파라미터 범위, 사고 필드, 일부 고급 기능에는 차이가 있습니다. 공식 OpenAI 호환 문서에 따라 항목별로 검증하고 모든 파라미터가 동일하게 동작한다고 가정하지 마세요.

2. Base URL 끝에 슬래시를 붙여야 하나요?

공식 문서에 슬래시가 있는 표기와 없는 표기가 모두 나온 적이 있고 SDK는 보통 자동으로 처리합니다. 핵심은 경로를 중복으로 붙이지 않는 것이므로 한 가지 표기를 골라 프로젝트 안에서 통일하세요.

3. 스트리밍 출력에서 추론 과정을 받을 수 있나요?

일부 모델은 사고 모드에서 reasoning_content를 반환합니다. 노출 여부는 제품 설계에 달려 있으며 최종 사용자에게는 보통 최종 답변만 보여 줍니다.

4. 도구 호출 형식이 OpenAI와 같은가요?

도구 정의와 반환 구조는 대체로 OpenAI 형식을 따르지만 파라미터 세부 사항은 모델에 따라 달라질 수 있습니다. 출시 전에 실제 도구로 한 차례 회귀 테스트를 하세요.

5. 공식과 게이트웨이의 모델명이 같은가요?

대부분 같은 모델명을 쓰지만 게이트웨이가 특정 모델을 개통했는지, 특정 파라미터를 지원하는지는 게이트웨이 콘솔과 모델 가격 페이지를 기준으로 하세요.

관련 글