ERNIE 5.1은 2026년 5월 9일에 출시되었고, 일주일 안에 Qianfan API가 서비스되기 시작했습니다. 이 글은 ERNIE 5.1을 코드에서 직접 호출하고, 스트리밍 응답을 처리하고, 도구 호출을 연결하고, Apidog로 테스트하는 구현 가이드입니다.
이 글을 따라 하면 다음을 바로 실행할 수 있습니다.
- Qianfan API 키 발급 및 환경 변수 설정
-
curl, Python, Node.js에서 ERNIE 5.1 호출 - Server-Sent Events 기반 스트리밍 처리
- OpenAI 호환 tool/function calling 구현
- Apidog에서 여러 LLM 공급업체 응답 비교
- 오류 처리와 재시도 래퍼 구성
아직 ERNIE 5.1 출시 분석을 읽지 않았다면 먼저 훑어보세요. DeepSeek V4, Kimi K2.6과의 벤치마크 및 장단점을 다룹니다. 이 글은 구현 편입니다.
1단계: Qianfan API 키 받기
ERNIE 5.1은 Baidu Intelligent Cloud의 Qianfan 플랫폼을 통해 제공됩니다. 별도의 “ERNIE API”가 있는 것이 아니라, 모든 요청은 Qianfan을 통해 라우팅됩니다.
API 키 생성 절차
- cloud.baidu.com에 접속해 Baidu Intelligent Cloud 계정을 생성하거나 로그인합니다.
- console.bce.baidu.com/qianfan에서 Qianfan 콘솔을 엽니다.
- API 키 관리에서 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 Forbidden: 키는 유효하지만 해당 작업 공간에서 ERNIE 5.1이 활성화되지 않음
403이면 Qianfan 콘솔로 돌아가서 ERNIE 5.1을 작업 공간의 허용 모델에 추가하세요.
3단계: Python에서 ERNIE 5.1 호출하기
엔드포인트가 OpenAI 호환이므로 공식 openai Python SDK를 그대로 사용할 수 있습니다.
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를 감싸는 내부 래퍼가 있다면, ERNIE 5.1 테스트는 보통 다음 두 값만 바꾸면 됩니다.
base_url = "https://qianfan.baidubce.com/v2"
model = "ernie-5.1"
이 접근 방식은 DeepSeek API 및 대부분의 OpenAI 호환 중국 모델 제공업체에도 적용됩니다.
4단계: 채팅 UI를 위한 토큰 스트리밍 구현하기
사용자 대면 채팅 UI에서는 전체 응답을 기다리는 것보다 스트리밍이 적합합니다. 요청에 stream: true를 추가하고 Server-Sent Events를 처리합니다.
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로 스트리밍을 디버깅할 때는 --no-buffer를 붙입니다.
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: {...}
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})")
일반적인 에이전트 루프는 다음 순서로 구성합니다.
- 사용자 메시지와
tools를 함께 모델에 전달합니다. - 모델이
tool_calls를 반환하는지 확인합니다. - 실제 애플리케이션 코드에서 해당 도구를 실행합니다.
- 실행 결과를
tool역할 메시지로 추가합니다. - 다시 모델을 호출합니다.
-
finish_reason == "stop"이고tool_calls가 비어 있으면 종료합니다.
도구 인수 파싱은 방어적으로 작성하세요. ERNIE 5.1은 때때로 깔끔한 JSON 문자열 대신 코드 펜스 안에 문자열화된 JSON을 반환할 수 있습니다.
import json
import re
def parse_tool_arguments(raw: str):
try:
return json.loads(raw)
except json.JSONDecodeError:
cleaned = re.sub(r"^```
json\s*|\s*
```$", "", raw.strip())
return json.loads(cleaned)
6단계: Node.js에서 ERNIE 5.1 호출하기
openai v5 이상을 사용하는 Node.js 프로젝트에서도 기본 URL만 Qianfan으로 바꾸면 됩니다.
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에 출시 중이므로, 응답 구조 검증은 애플리케이션 코드에서 직접 수행하는 것이 안전합니다.
예를 들어 Node.js에서는 다음처럼 최소 검증을 추가할 수 있습니다.
const content = completion.choices[0].message.content;
let parsed;
try {
parsed = JSON.parse(content);
} catch {
throw new Error("Model did not return valid JSON");
}
if (!Array.isArray(parsed.tips)) {
throw new Error("Expected `tips` to be an array");
}
console.log(parsed);
7단계: Apidog로 ERNIE 5.1, DeepSeek V4, Kimi K2.6 비교하기
ERNIE 5.1, DeepSeek V4, Kimi K2.6 중 어떤 모델을 쓸지 결정해야 한다면 터미널에서 수동으로 비교하지 마세요. Apidog에서 공급업체별 요청을 같은 프로젝트 안에 구성하면 같은 프롬프트로 결과를 반복 비교할 수 있습니다.
60초 설정
- Apidog를 열고
LLM bake-off라는 새 프로젝트를 생성합니다.
- 환경 변수를 추가합니다.
QIANFAN_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
- 공급업체별로 요청을 만듭니다.
| 공급업체 | 기본 URL | 모델 |
|---|---|---|
| Qianfan | https://qianfan.baidubce.com/v2 |
ernie-5.1 |
| DeepSeek | 해당 공급업체 기본 URL | deepseek-chat |
| Moonshot/Kimi | 해당 공급업체 기본 URL | kimi-k2-6 |
- 세 요청 모두에 동일한
messages배열을 사용합니다.
{
"model": "ernie-5.1",
"messages": [
{
"role": "system",
"content": "You are a strict API reviewer."
},
{
"role": "user",
"content": "Review this endpoint design and suggest improvements: POST /users/{id}/activate"
}
],
"temperature": 0.2
}
- Apidog의 실행 기능으로 요청을 보내고 응답 품질, 지연 시간, 토큰 사용량을 비교합니다.
무료 티어에서도 이 정도 테스트는 충분히 처리할 수 있습니다. Apidog는 환경별 요청 기록을 저장하므로, 다음 주에 새 모델 버전이 나오더라도 같은 평가를 다시 실행할 수 있습니다.
다중 공급업체 테스트에 대한 자세한 내용은 Test local LLMs as APIs 및 GLM 5.1 API 가이드를 참고하세요.
가격, 속도 제한, 할당량 확인하기
ERNIE 5.1의 공개 Qianfan 가격은 출시 게시물에 포함되지 않았습니다. 내부 문서나 비용 추정에 숫자를 쓰기 전에 반드시 Qianfan 콘솔의 최신 요금표를 확인하세요.
구현 시에는 다음 세 가지를 기록하는 것이 좋습니다.
1. 속도 제한은 작업 공간 단위입니다
새 계정은 낮은 QPS 제한으로 시작할 수 있습니다. 테스트가 끝나고 트래픽을 늘리려면 콘솔에서 한도를 올리세요.
2. 토큰 사용량은 응답에 포함됩니다
응답의 usage 필드를 호출 단위로 저장하세요.
{
"usage": {
"prompt_tokens": 42,
"completion_tokens": 318,
"total_tokens": 360
}
}
비용 회계를 대시보드에만 의존하지 말고, 애플리케이션 로그에도 남기는 것이 좋습니다.
3. 프롬프트 캐싱은 자동이 아닙니다
Qianfan은 현재 ERNIE 5.1에 대한 프롬프트 캐싱 프리미티브를 제공하지 않습니다. 2,000토큰 시스템 프롬프트를 매번 보내면 호출할 때마다 비용이 발생합니다.
긴 시스템 프롬프트를 쓰는 경우 다음을 고려하세요.
- 공통 지시사항을 짧게 유지
- 도메인 지식은 검색/RAG로 주입
- 반복 태스크는 프롬프트 템플릿을 압축
- 호출당
usage.total_tokens기록
오류 처리 체크리스트
실제로 자주 만나는 오류는 다음과 같습니다.
| 상태 | 의미 | 해결책 |
|---|---|---|
| 401 | Bearer 토큰이 잘못되었거나 만료됨 | 콘솔에서 키 재생성 |
| 403 | 이 작업 공간에서 모델이 활성화되지 않음 | 콘솔에 ERNIE 5.1 추가 |
| 429 | 속도 제한 초과 | 백오프 + 지터와 함께 재시도 |
400 (invalid messages) |
메시지 역할 순서가 잘못됨 | user/assistant 교대 확인 |
| 500/502 | Qianfan 측 일시적 오류 | 한 번 재시도하고 계속되면 상태 페이지 확인 |
프로덕션에서는 모든 호출을 제한된 지수 백오프로 감싸세요. 최대 3회 정도가 적절합니다. 또한 응답 헤더의 request_id를 기록하세요. Baidu 지원팀에 문의할 때 필요할 수 있습니다.
최소 프로덕션용 Python 래퍼
아래 래퍼는 기본 채팅 호출, 속도 제한, 일시적 서버 오류 재시도를 처리합니다.
import os
import time
import random
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:
sleep_seconds = (2 ** attempt) + random.random()
time.sleep(sleep_seconds)
except APIError as e:
should_retry = (
e.status_code is not None
and e.status_code >= 500
and attempt < max_retries - 1
)
if should_retry:
time.sleep(1 + attempt)
continue
raise
raise RuntimeError("ERNIE 5.1 retries exhausted")
사용 예시는 다음과 같습니다.
response = chat([
{
"role": "system",
"content": "You are a concise API design reviewer."
},
{
"role": "user",
"content": "Review this route: PATCH /users/{id}/status"
}
])
print(response.choices[0].message.content)
이 래퍼를 기반으로 스트리밍, 도구 호출, JSON 검증을 추가하면 됩니다.
자주 묻는 질문
ERNIE 5.1 API는 무료인가요?
아닙니다. Qianfan은 사용량 기반 과금 방식입니다. 영구적인 무료 티어는 없지만, 새 계정에 체험 크레딧이 제공되는 경우가 있습니다.
무료로 실험하려면 ernie.baidu.com 채팅 UI를 사용하거나 무료 LLM 옵션을 살펴보세요.
ERNIE 5.1을 로컬에서 실행할 수 있나요?
아닙니다. 공개된 가중치는 없습니다.
온프레미스 배포가 필수라면 DeepSeek V4를 로컬에서 실행하는 방법 또는 2026년 최고의 로컬 LLM을 참고하세요.
OpenAI SDK가 변경 없이 작동하나요?
예. 다음 값만 Qianfan에 맞게 설정하면 됩니다.
api_key = os.environ["QIANFAN_API_KEY"]
base_url = "https://qianfan.baidubce.com/v2"
model = "ernie-5.1"
함수 호출, 스트리밍, response_format: json_object는 모두 사용할 수 있습니다. 다만 엄격한 json_schema 유효성 검사는 아직 출시 중이므로 코드에서 직접 검증하세요.
ERNIE 5.1은 중국어와 영어 프롬프트를 모두 잘 처리하나요?
둘 다 높은 수준으로 지원됩니다. Arena Search 점수 1,223점은 혼합 언어 투표 풀에서 나왔습니다. 기술 영어 작업, 코드, API 설계 작업에서도 경쟁력이 있으며, 중국어 창작 글쓰기에서는 중국 모델 중 최고 수준입니다.
최대 출력 길이는 얼마인가요?
공식적으로 게시되지 않았습니다. 실제 사용에서는 단일 턴 응답이 모델 완료 전 약 8K 토큰으로 제한되는 경우가 있습니다. 장문 생성을 해야 한다면 여러 단계로 나누어 생성하고 이어 붙이는 방식이 안전합니다.
마무리
ERNIE 5.1을 앱에 붙이는 핵심은 간단합니다.
- Qianfan에서 API 키를 발급합니다.
- OpenAI SDK의
base_url을https://qianfan.baidubce.com/v2로 설정합니다. - 모델을
ernie-5.1로 지정합니다. - 스트리밍, 도구 호출, JSON 검증, 재시도 로직을 애플리케이션 요구사항에 맞게 추가합니다.
- Apidog에서 Qianfan 요청을 다른 LLM 공급업체와 함께 테스트하고 문서화합니다.
Top comments (0)