ERNIE 5.1은 2026년 5월 9일에 출시되었고, 일주일 안에 Qianfan API가 서비스되기 시작했습니다. 모델을 직접 코드에서 호출하거나, 도구 호출을 라우팅하거나, Apidog와 함께 에이전트 루프에 연결하고 싶다면 이 가이드는 계정, 키, 요청 본문, 스트리밍, 도구 사용, 오류 처리 등 모든 과정을 안내합니다.
우리는 실용적인 내용을 다룰 것입니다. 이 가이드가 끝나면 작동하는 curl, Python, Node 스니펫과 Apidog에 삽입할 수 있는 요청 컬렉션을 갖게 될 것입니다.
아직 ERNIE 5.1 출시 분석을 읽지 않았다면, 먼저 훑어보세요. DeepSeek V4 및 Kimi K2.6과 비교한 벤치마크 및 장단점을 다룹니다. 이 게시물은 구현 동반자입니다.
1단계: Qianfan API 키 받기
ERNIE 5.1은 Baidu Intelligent Cloud의 Qianfan 플랫폼을 통해 서비스됩니다. 별도의 "ERNIE API"는 없으며, 모든 것은 Qianfan을 통해 라우팅됩니다.
- cloud.baidu.com으로 이동하여 Baidu Intelligent Cloud 계정을 생성하거나 로그인합니다. 해외 개발자는 이메일로 가입할 수 있지만, 일부 기업 기능은 여전히 중국 본토 전화번호가 필요합니다.
- console.bce.baidu.com/qianfan에서 Qianfan 콘솔을 엽니다.
- API 키 관리(
API Key 관리)에서 API 키 생성을 클릭합니다. 작업 공간을 선택하고 채팅 완성 서비스에 대한 액세스 권한을 부여합니다. - 키를 복사합니다.
bce-v3/ALTAK-xxxx/xxxx와 유사하게 생겼습니다. 소스 코드에 저장하지 말고 환경 변수에 저장하십시오.
export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"
미리 알아야 할 두 가지 사항이 있습니다. 첫째, 새로운 v2 엔드포인트는 단일 Bearer 토큰을 사용합니다. 이전 v1 OAuth access_token 플로우는 더 이상 사용되지 않으므로 새로운 코드를 작성할 때 사용해서는 안 됩니다. 둘째, ERNIE 5.1은 처음부터 유료 모델입니다. 첫 요청 전에 소액의 잔액(테스트에 ¥10이면 충분)을 충전하십시오.
2단계: curl로 OpenAI 호환 엔드포인트 호출하기
Qianfan은 OpenAI 호환 채팅 완성 엔드포인트를 노출하므로, 이미 OpenAI 형식을 사용하는 스택의 모든 것이 기본 URL 스왑 및 모델 ID 변경으로 작동합니다.
기본 URL: https://qianfan.baidubce.com/v2 모델 ID: ernie-5.1 (조기 액세스 기능을 위한 ernie-5.1-preview도 사용 가능)
최소 유효 요청:
curl https://qianfan.baidubce.com/v2/chat/completions \
-H "Authorization: Bearer $QIANFAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ernie-5.1",
"messages": [
{"role": "system", "content": "You are a senior API designer."},
{"role": "user", "content": "Sketch a REST schema for a GitHub-style PR review API. Be concise."}
],
"temperature": 0.3
}'
표준 OpenAI 형태의 응답을 받습니다:
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1746780000,
"model": "ernie-5.1",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "..." },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 318,
"total_tokens": 360
}
}
401 Unauthorized 오류가 발생하면 키가 잘못되었거나 만료된 것입니다. 403 오류가 발생하면 키는 유효하지만 모델이 이 작업 공간에서 활성화되지 않은 것입니다. 콘솔로 돌아가서 ERNIE 5.1을 작업 공간의 허용된 모델에 추가하십시오.
3단계: Python에서 ERNIE 5.1 호출하기
엔드포인트가 OpenAI 호환이므로 공식 openai Python SDK는 그대로 작동합니다. Qianfan으로 연결하십시오.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["QIANFAN_API_KEY"],
base_url="https://qianfan.baidubce.com/v2",
)
response = client.chat.completions.create(
model="ernie-5.1",
messages=[
{"role": "system", "content": "You explain APIs in plain English."},
{"role": "user", "content": "Why would I use server-sent events over WebSockets for a chat UI?"},
],
temperature=0.4,
)
print(response.choices[0].message.content)
print(f"\nTokens used: {response.usage.total_tokens}")
코드베이스에 이미 OpenAI SDK를 감싸는 래퍼가 있다면, A/B 테스트를 위해 ERNIE 5.1을 교체하는 것은 한 줄 변경으로 가능합니다. 이와 동일한 방법이 DeepSeek의 API 및 대부분의 다른 중국 모델 제공업체에도 적용됩니다.
4단계: 채팅 스타일 UI를 위한 토큰 스트리밍
사용자 대면 채팅의 경우 스트리밍이 필요합니다. stream: true로 설정하고 서버 전송 이벤트를 소비하십시오.
stream = client.chat.completions.create(
model="ernie-5.1",
messages=[{"role": "user", "content": "Write a haiku about API versioning."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
디버깅을 위한 curl 동등 코드:
curl https://qianfan.baidubce.com/v2/chat/completions \
-H "Authorization: Bearer $QIANFAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ernie-5.1",
"stream": true,
"messages": [{"role": "user", "content": "Stream a 3-sentence joke."}]
}' \
--no-buffer
스트림 형식은 OpenAI와 동일합니다: data: {...} 줄은 data: [DONE]으로 종료됩니다.
5단계: 도구와 함께 ERNIE 5.1 사용하기 (에이전트 부분)
ERNIE 5.1이 출시 헤드라인을 장식하는 부분입니다. 이 모델은 τ³-bench 및 SpreadsheetBench-Verified에서 DeepSeek-V4-Pro보다 높은 점수를 기록했으며, 이는 도구 호출이 데모뿐만 아니라 실제 프로덕션에서도 작동한다는 의미입니다.
OpenAI 함수 호출과 동일한 스키마:
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, e.g. Singapore"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["city"],
},
},
}
]
response = client.chat.completions.create(
model="ernie-5.1",
messages=[{"role": "user", "content": "What's the weather in Tokyo right now?"}],
tools=tools,
tool_choice="auto",
)
tool_calls = response.choices[0].message.tool_calls
if tool_calls:
call = tool_calls[0]
print(f"Model wants to call: {call.function.name}({call.function.arguments})")
코드가 실제 도구를 실행한 후, 그 결과를 tool 역할 메시지로 추가하고 다시 호출합니다. 루프는 finish_reason == "stop"이고 tool_calls가 비어 있을 때 종료됩니다.
한 가지 주의할 점: ERNIE 5.1은 때때로 도구 인수를 깔끔한 JSON 문자열이 아닌 코드 펜스 내의 문자열화된 JSON으로 반환합니다. try/except로 래핑된 json.loads()를 사용하여 방어적으로 파싱하고, 실패하면 재시도하기 전에 ```json 펜스를 제거하십시오.
6단계: Node.js에서 ERNIE 5.1 호출하기
openai v5+를 사용하는 모든 Node 프로젝트에 즉시 적용 가능:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.QIANFAN_API_KEY,
baseURL: "https://qianfan.baidubce.com/v2",
});
const completion = await client.chat.completions.create({
model: "ernie-5.1",
messages: [
{ role: "user", content: "Return a JSON object with 3 API design tips." },
],
response_format: { type: "json_object" },
});
console.log(completion.choices[0].message.content);
response_format: { type: "json_object" }는 작동하며 신뢰할 수 있습니다. 엄격한 JSON 스키마(json_schema)는 아직 Qianfan에 출시 중이므로, 제약 조건을 신뢰하기보다 코드에서 응답 형식을 확인하십시오.
7단계: Apidog로 테스트 및 비교
ERNIE 5.1, DeepSeek V4, Kimi K2.6 중에서 선택해야 한다면 터미널에서 하지 마십시오. Apidog를 사용하여 공급업체별 폴더 하나, 동일한 요청 본문, 그리고 API 키별로 저장된 환경을 갖춘 단일 작업 공간을 만드십시오.
60초 설정:
- Apidog를 열고 "LLM bake-off"라는 새 프로젝트를 생성합니다.
QIANFAN_API_KEY, DEEPSEEK_API_KEY, MOONSHOT_API_KEY를 변수로 사용하여 환경을 추가합니다.
model이 각각 ernie-5.1, deepseek-chat, kimi-k2-6으로 설정된 각 공급업체의 기본 URL을 가리키는 세 가지 요청을 생성합니다.
세 가지 모두에 동일한 messages 배열을 고정합니다. Apidog의 "실행" 기능을 사용하여 동시에 요청을 보내고 출력을 비교합니다.
무료 티어에서도 이 작업을 편안하게 처리할 수 있습니다. Apidog는 환경별 요청 기록을 저장하므로, 다음 주에 돌아와서 새로운 모델 버전에 대해 정확히 동일한 평가를 다시 실행할 수 있습니다. tmux 창에서 curl을 돌보는 것보다 훨씬 낫습니다.
다중 공급업체 테스트에 대한 자세한 내용은 Test local LLMs as APIs 및 GLM 5.1 API 가이드를 참조하십시오.
가격 책정, 속도 제한 및 할당량
ERNIE 5.1의 공개 Qianfan 가격 책정은 출시 게시물에 없었습니다. 내부적으로 숫자를 인용하기 전에 라이브 콘솔 요금표를 확인하십시오. 기다리는 동안 세 가지 실용적인 팁:
- 기본 속도 제한은 작업 공간 범위입니다. 새 계정은 낮은 QPS 제한으로 시작합니다. 테스트를 마친 후 콘솔에서 이를 높이십시오.
- 토큰 사용량은 응답에 표시됩니다.
usage필드는 호출당prompt_tokens,completion_tokens,total_tokens를 제공합니다. 요청당 이를 기록하십시오. 비용 회계를 위해 대시보드만 신뢰하지 마십시오. - 캐싱은 자동이 아닙니다. Anthropic과 달리 Qianfan은 현재 ERNIE 5.1에 대한 프롬프트 캐싱 프리미티브를 제공하지 않습니다. 2,000토큰 시스템 프롬프트가 있다면, 호출할 때마다 비용을 지불하게 됩니다. 이를 고려하여 아키텍처를 설계하십시오.
당신을 구할 오류 처리
실제로 발생할 오류의 대략적인 빈도 순서:
| 상태 | 의미 | 해결책 |
|---|---|---|
| 401 | Bearer 토큰이 잘못되었거나 만료됨 | 콘솔에서 재생성 |
| 403 | 이 작업 공간에서 모델이 활성화되지 않음 | 콘솔에 ERNIE 5.1 추가 |
| 429 | 속도 제한 초과 | 백오프 + 지터와 함께 재시도 |
400 (invalid messages) |
메시지 역할 순서가 잘못됨 | 사용자/어시스턴트 교대 확인 |
| 500/502 | Qianfan 측 일시적 오류 | 한 번 재시도; 계속되면 상태 페이지 확인 |
모든 호출을 최대 3회 시도로 제한된 지수 백오프 재시도로 래핑하십시오. 프로덕션 환경에서는 응답 헤더에서 request_id를 기록하십시오. Baidu 지원팀은 문제를 디버깅하기 위해 필요합니다.
최소한의 프로덕션용 래퍼
오늘 ERNIE 5.1을 실제 앱에 통합하고 싶다면, 다음은 부끄럽지 않은 최소한의 래퍼입니다:
import os, time, random, json
from openai import OpenAI, RateLimitError, APIError
client = OpenAI(
api_key=os.environ["QIANFAN_API_KEY"],
base_url="https://qianfan.baidubce.com/v2",
)
def chat(messages, *, model="ernie-5.1", temperature=0.3, max_retries=3):
for attempt in range(max_retries):
try:
return client.chat.completions.create(
model=model,
messages=messages,
temperature=temperature,
)
except RateLimitError:
time.sleep((2 ** attempt) + random.random())
except APIError as e:
if e.status_code and e.status_code >= 500 and attempt < max_retries - 1:
time.sleep(1 + attempt)
continue
raise
raise RuntimeError("ERNIE 5.1 retries exhausted")
이는 80%의 경우를 처리합니다. 도구 루프 및 스트리밍을 위해서는 이를 기반으로 구축하십시오.
자주 묻는 질문
ERNIE 5.1 API는 무료인가요? 아닙니다. Qianfan은 사용한 만큼 지불하는 방식입니다. 영구적인 무료 티어는 없지만, 새 계정에는 가끔 체험 크레딧이 제공됩니다. 무료로 실험하려면 ernie.baidu.com 채팅 UI를 사용하거나 무료 LLM 옵션을 살펴보십시오.
ERNIE 5.1을 로컬에서 실행할 수 있나요? 아닙니다. 공개된 가중치는 없습니다. 온프레미스 배포가 필수라면 DeepSeek V4를 로컬에서 실행하는 방법 또는 2026년 최고의 로컬 LLM을 대신 살펴보십시오.
OpenAI SDK가 변경 없이 작동하나요? 예, base_url을 https://qianfan.baidubce.com/v2로, api_key를 Qianfan 키로 설정하면 작동합니다. model 필드는 OpenAI 모델 ID가 아닌 Qianfan 모델 ID를 사용합니다. 함수 호출, 스트리밍 및 response_format: json_object는 모두 작동합니다. 엄격한 json_schema 유효성 검사는 아직 출시 중입니다.
ERNIE 5.1은 중국어 및 영어 프롬프트를 어떻게 처리하나요? 둘 다 최고 수준으로 지원됩니다. Arena Search 점수 1,223점은 혼합 언어 투표 풀에서 나왔습니다. 기술 영어 작업(코드, API 설계)의 경우 폐쇄형 프론티어 모델과 경쟁력이 있으며, 중국어 창작 글쓰기에서는 중국 모델 중 최고 수준입니다.
최대 출력 길이는 얼마인가요? 공식적으로 게시되지 않았습니다. 실제로는 단일 턴 응답이 모델이 완료되기 전 약 8K 토큰으로 제한됩니다. 장문 생성을 위해서는 분할하여 계속하십시오.
ERNIE 5.1에서 에이전트를 구축하시나요? Apidog를 다운로드하고 OpenAI 호환 요청 컬렉션을 사용하여 Qianfan 엔드포인트를 다른 서비스와 함께 모의, 테스트 및 문서화하십시오.