Tencent TokenHub API 연결 안내
사이트와 리전, 실제 모델 ID를 확인하고 채팅, 스트림과 사용량을 검증합니다.
사이트, 권한과 모델부터 확인
Tencent TokenHub의 OpenAI 호환 Chat Completions를 사용하는 절차입니다. 권한이 있는 계정, 대상 리전의 TokenHub API 키와 활성화된 모델 서비스가 필요합니다. 프로토콜 호환은 요청 형식을 뜻하며 OpenAI나 Anthropic의 모든 모델을 공급한다는 의미가 아닙니다. SDK 이름만으로 GPT 또는 Claude의 이용 가능성을 판단하지 마세요.
사이트, 리전, 과금 계정, 모델 활성화와 네트워크를 기록합니다. 모델 목록과 계정 활성화는 별개입니다. online 상태는 ID 선택에 도움이 되지만 권한, 잔액과 할당량을 대신 확인해 주지는 않습니다. Responses, 도구, 캐시, 추론과 멀티모달도 모델별로 점검해야 합니다.
현재 리전 주소 선택
기본 Base URL은 싱가포르 https://tokenhub-intl.tencentmaas.com/v1 또는 광저우 https://tokenhub.tencentmaas.com/v1입니다. 예제는 싱가포르를 사용합니다. 키는 서비스가 활성화된 사이트·리전과 맞아야 하며 서로 바꿔 쓸 수 없습니다. 오래된 안내의 다른 도메인을 가져오지 말고 대체 주소도 현재 공식 표로 확인하세요.
싱가포르의 자원 스케줄링 범위는 글로벌입니다. 접속 주소가 싱가포르라고 추론이 그곳에만 머문다는 보장은 없습니다. 광저우의 범위는 다릅니다. 민감 자료를 쓰기 전에 처리, 로그와 계약 조건을 확인하고 도메인 변경으로 승인된 데이터 경계를 우회하지 마세요.
설치와 실제 모델 ID 조회
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai
다음은 자리표시자입니다. TOKENHUB_API_KEY는 승인된 서버 환경에서 주입하고 브라우저나 저장소에 넣지 마세요. 모델 값은 목록을 확인한 뒤 바꿉니다.
export TOKENHUB_BASE_URL='https://tokenhub-intl.tencentmaas.com/v1'
export TOKENHUB_MODEL='YOUR-ACTUAL-ONLINE-MODEL-ID'
초기화 코드를 tokenhub_chat.py로 저장합니다. client.models.list()는 인증된 GET /v1/models에 대응하며 키 대신 ID와 status를 출력합니다. online 텍스트 모델을 선택하고 콘솔에서 계정의 활성화도 확인한 뒤 TOKENHUB_MODEL을 설정하세요. 날짜가 있는 예제가 모델의 장기 가용성을 보장하지는 않습니다.
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ["TOKENHUB_BASE_URL"],
api_key=os.environ["TOKENHUB_API_KEY"],
timeout=30.0,
max_retries=0,
)
for item in client.models.list().data:
print(item.id, getattr(item, "status", "status unavailable"))
최소 채팅 요청
테스트 권한과 비용을 승인한 뒤 다음을 추가하고 python tokenhub_chat.py를 실행하세요. 일반 텍스트와 max_tokens 지원 모델을 선택합니다. 출력128, 제한 시간30초와 자동 재시도0은 예제 제어값이며 서비스 할당량이나 응답 보장이 아닙니다.
request = {
"model": os.environ["TOKENHUB_MODEL"],
"messages": [{"role": "user", "content": "Reply with one short greeting."}],
"max_tokens": 128,
}
answer = client.chat.completions.create(**request)
if not answer.choices:
raise RuntimeError("No completion choice returned")
print(answer.choices[0].message.content or "")
print("finish_reason:", answer.choices[0].finish_reason)
print(answer.usage.model_dump() if answer.usage else "usage unavailable")
finish reason으로 정상 완료, 잘림, 필터링과 도구 요청을 구분합니다. HTTP200이나 일부 텍스트만으로 업무 성공을 증명할 수 없습니다. 짧은 단일 호출로 권한과 계량을 확인한 뒤 동시 실행을 늘리세요.
스트림과 사용량 처리
비스트리밍 호출을 다음으로 바꿉니다. 빈 choices를 확인하고 delta.content와 usage를 별도로 읽습니다. 종료 이유가 나와도 끝까지 읽어 후속 사용량을 놓치지 마세요. 캐시 세부 항목은 모델마다 다를 수 있고 usage 누락은 무료를 의미하지 않습니다. 이 예제는 추론 내용과 도구 인수를 처리하지 않습니다.
from openai import APIError
usage = None
finish_reason = None
try:
with client.chat.completions.create(
**request, stream=True, stream_options={"include_usage": True}
) as events:
for part in events:
if part.usage is not None:
usage = part.usage
if not part.choices:
continue
choice = part.choices[0]
if choice.delta.content:
print(choice.delta.content, end="", flush=True)
if choice.finish_reason is not None:
finish_reason = choice.finish_reason
except APIError:
print("Stream failed; partial output is not a completed task.")
raise
print()
print("finish_reason:", finish_reason)
print(usage.model_dump() if usage else "usage unavailable")
SDK 예외는 실패로 기록하세요. 직접 만든 SSE 파서는 중간 error 프레임도 감지해야 합니다. HTTP200 헤더 뒤에도 오류가 날 수 있습니다. 일부 답변을 완료로 보고하거나 재시도 때 외부 작업을 중복 실행하지 마세요.
오류 조사와 검수
- 401/401002: 키의 유효성과 싱가포르·광저우 사이트 일치를 확인합니다.
- 402/402xxx: 모델 활성화, 잔액과 과금을 확인하고 곧바로 프로토콜 미지원으로 판단하지 않습니다.
- 400/404: ID, 경로와 모델 매개변수를 점검하고 선택 기능부터 줄입니다.
- 429/429xxx: 요청, Token과 동시 실행을 확인하며 Retry-After가 있으면 따르고 재시도 총량을 제한합니다.
- 시간 초과/5xx/스트림 오류: 민감 정보를 뺀 요청 ID와 시간을 남기고 상태를 확인합니다. 전체 인증 헤더를 저장하지 않습니다.
모델·경로별 사용량을 청구와 대조하고 캐시, 추론과 추가 기능을 확인하세요. 다른 채널의 가격이나 절감 약속을 가져오지 마세요. 출시 전 잘림, 빈 사용량 청크, 중단, 권한과 잔액 부족을 검수하며 출력, 동시 실행과 전체 작업 시간을 제한합니다. 로그 최소화, 키 교체와 종료 절차의 책임자도 정하세요.
예제는 오프라인 구문 및 합성 스트림 검사만 거쳤습니다. 실제 키 읽기, 계정 모델 목록 조회나 모델 호출은 하지 않았습니다. 계정 가용성과 비용은 승인된 환경에서 확인해야 합니다.
공식 자료
확인일: 2026-10-17.