Alibaba Cloud Model Studio API 연결 안내

리전, 워크스페이스와 모델부터 확인

Alibaba Cloud 국제 사이트 Model Studio의 OpenAI 호환 텍스트 채팅 API를 사용하는 절차입니다. 권한이 있는 계정, 활성화된 서비스, 사용 가능한 워크스페이스와 모델 권한이 필요합니다. 접속 리전, 워크스페이스, 서비스 배포 범위, 실제 모델 ID, 과금 계획과 호출 제한을 기록하세요. 일반 모델 목록의 이름이 해당 워크스페이스에서 호출할 수 있는 ID라는 보장은 없습니다.

접속·저장 위치와 추론 위치를 정하는 배포 범위는 따로 확인합니다. OpenAI 호환이라는 말만으로 특정 모델, 글로벌 추론이나 구독 계획의 이용 가능성을 알 수 없습니다. 이 안내는 워크스페이스 생성, 할당량 신청이나 유료 서비스 활성화를 대신 수행하지 않습니다.

엔드포인트와 키를 맞추기

Workspace Management에서 API Host를 복사하고 선택한 프로토콜의 경로를 붙입니다. OpenAI 호환 경로는 /compatible-mode/v1이며 원래 DashScope /api/v1은 다른 API입니다. 아래는 싱가포르 워크스페이스 전용 호스트의 예시 형식입니다. 자리표시자를 바꾸고 다른 리전은 콘솔의 실제 Host를 사용하세요. 도메인을 추측해서 리전을 바꾸지 마세요.

키는 리전, 대상 워크스페이스와 과금 계획에 맞아야 합니다. 종량제 키를 Coding Plan이나 Token Plan 전용 주소와 섞으면 안 됩니다. 현재 이 계획들은 대화형 코딩 도구용이며 백엔드 모델 서비스용이 아닙니다. 이전 안내와 다르면 현재 Base URL 문서와 콘솔을 먼저 확인하세요. 국제 사이트와 중국 사이트의 계정, 할당량과 가격이 같다고 가정하지 않습니다.

설치와 자리표시자 설정

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

DASHSCOPE_API_KEY는 승인된 서버 환경에서 안전하게 주입하세요. 아래의 공개 구조 예시는 그대로 성공하지 않습니다. 텍스트 채팅, 스트리밍과 max_tokens 지원을 확인한 후 MODEL_STUDIO_MODEL을 실제 ID로 바꾸세요. 스트리밍만 지원하는 모델도 있으므로 비스트리밍 요청 실패만으로 이용 불가라고 판단하지 않습니다.

export MODEL_STUDIO_BASE_URL='https://YOUR-WORKSPACE.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1'
export MODEL_STUDIO_MODEL='YOUR-ACTUAL-TEXT-MODEL-ID'

최소 스트림 호출과 사용량 읽기

코드를 model_studio_chat.py로 저장하고 비용과 테스트 권한을 확인한 뒤 python model_studio_chat.py를 실행합니다. 출력 상한128, 클라이언트 제한 시간30초와 자동 재시도0은 테스트 제어값이며 서비스 할당량, 최대 처리 시간이나 지원 보장이 아닙니다.

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["MODEL_STUDIO_BASE_URL"],
    api_key=os.environ["DASHSCOPE_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
usage = None
finish_reason = None
with client.chat.completions.create(
    model=os.environ["MODEL_STUDIO_MODEL"],
    messages=[{"role": "user", "content": "Reply with one short greeting."}],
    max_tokens=128,
    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
print()
print("finish_reason:", finish_reason)
print(usage.model_dump() if usage else "usage unavailable")

include_usage는 사용량 반환을 요청합니다. 마지막 usage 청크의 choices는 비어 있을 수 있으므로 usage를 먼저 읽고 목록을 확인하세요. 텍스트는 delta.content에 있으며 비스트리밍의 message.content와 다릅니다. finish reason을 받자마자 종료하면 이후의 사용량 청크를 놓칠 수 있습니다.

연결 중단으로 usage를 받지 못했다면 미확인으로 기록하고0이나 무료로 해석하지 않습니다. 이 파서는 일반 텍스트용이며 도구 호출, 추론 내용, 이미지와 오디오는 별도 구조 처리가 필요합니다. 업무가 부분 결과를 명시적으로 허용하지 않는다면 일부 출력만으로 완료라고 보고하지 마세요.

오류 유형별 조사

• 401/403: 키의 리전, 워크스페이스, 계획과 권한을 확인합니다. 전체 인증 정보를 문의에 붙이지 마세요.
• 404·모델 없음: Host, 호환 경로, 실제 ID와 워크스페이스 모델 목록을 확인합니다. 다른 리전의 오래된 접미사를 가져오지 않습니다.
• 400: 입력, 출력 상한과 선택 매개변수를 확인하고 짧은 일반 텍스트로 원인을 좁힙니다.
• 429: 요청 수, Token과 동시 실행 제한을 함께 점검하고 반환 오류와 공식 제한 문서에 따라 제한된 백오프를 적용합니다.
• 시간 초과/5xx: 민감 정보를 뺀 요청 식별자와 시간을 남기고 재시도를 제한합니다. 부분 출력을 전체 성공으로 처리하지 않습니다.

비용, 안전과 검수

실제 모델, 리전과 배포 범위로 사용량을 콘솔·청구서와 대조합니다. 스트리밍도 생성 비용이 들며 클라이언트 연결 중단이 서버의 즉시 취소를 증명하지 않습니다. 출력, 동시 실행, 전체 작업 시간과 도구 반복을 각각 제한하세요. 예산 알림은 실제 호출 차단이 아닙니다. 이 글은 단가, 할인이나 계획 보장을 제공하지 않습니다.

현재 보관 정책은 추론 입력·출력을 기본30일 이내 보관하되 법률·안전상 예외를 둡니다. ZDR은 승인과 지원 모델·경로 조건이 있으며 계량, 안전 기록과 상태 유지 기능에는 별도 경계가 있습니다. 민감 데이터 사용 전 실제 워크스페이스와 계약을 확인하고 앱 로그도 통제하세요.

정상 완료, 잘림, 빈 choices 사용량 청크, 연결 중단, 제한과 권한 실패를 검수하고 모델 ID, 경로, finish reason과 계량을 남깁니다. 예제는 오프라인 구문 검사만 거쳤으며 키 읽기, 실제 모델 호출이나 계정별 이용 가능성 확인은 하지 않았습니다.

공식 자료

확인일: 2026-10-17. 현재 워크스페이스와 공식 문서를 기준으로 설정하세요.

• Base URL과 과금 계획
• 리전과 배포 범위
• 스트리밍과 usage
• 호출 제한
• 보관 정책과 ZDR