DEV Community

Cover image for Hướng Dẫn Sử Dụng API ERNIE 5.1 Chi Tiết
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng Dẫn Sử Dụng API ERNIE 5.1 Chi Tiết

ERNIE 5.1 ra mắt ngày 9 tháng 5 năm 2026, và trong vòng một tuần, API Qianfan đã hỗ trợ mô hình này. Nếu bạn muốn gọi ERNIE 5.1 từ mã nguồn, định tuyến tool call, hoặc đưa nó vào vòng lặp tác nhân với Apidog, bài viết này hướng dẫn từng bước: tạo tài khoản, lấy khóa, gửi request, streaming, tool calling và xử lý lỗi.

Dùng thử Apidog ngay hôm nay

Mục tiêu là có thể chạy được ngay. Bạn sẽ có ví dụ curl, Python, Node.js và một bộ request có thể nhập vào Apidog để kiểm thử.

Nếu bạn chưa đọc bài phân tích ra mắt ERNIE 5.1, hãy đọc lướt trước; bài đó bao gồm benchmark và so sánh với DeepSeek V4 và Kimi K2.6. Bài này tập trung vào phần triển khai.

ERNIE 5.1

Bước 1: Lấy khóa API Qianfan

ERNIE 5.1 được cung cấp qua nền tảng Qianfan của Baidu Intelligent Cloud. Không có “API ERNIE” riêng biệt; tất cả request đều đi qua Qianfan.

Thực hiện các bước sau:

  1. Truy cập cloud.baidu.com và tạo hoặc đăng nhập tài khoản Baidu Intelligent Cloud. Nhà phát triển quốc tế có thể đăng ký bằng email; một số tính năng doanh nghiệp vẫn yêu cầu số điện thoại Trung Quốc đại lục.
  2. Mở bảng điều khiển Qianfan tại console.bce.baidu.com/qianfan.
  3. Vào Quản lý khóa API (API Key 管理) và chọn Tạo khóa API.
  4. Chọn workspace và cấp quyền truy cập dịch vụ chat-completions.
  5. Sao chép khóa. Khóa có dạng bce-v3/ALTAK-xxxx/xxxx.

Không hard-code khóa trong source code. Lưu vào biến môi trường:

export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"
Enter fullscreen mode Exit fullscreen mode

Có hai điểm cần lưu ý:

  • Endpoint v2 dùng Bearer token duy nhất. Luồng access_token OAuth v1 cũ đang bị loại bỏ, không nên dùng cho mã mới.
  • ERNIE 5.1 là mô hình trả phí ngay từ đầu. Hãy nạp một số dư nhỏ, ví dụ ¥10, trước khi gửi request đầu tiên.

Bước 2: Gửi request bằng curl tới endpoint tương thích OpenAI

Qianfan cung cấp endpoint chat-completions tương thích với OpenAI. Nếu hệ thống của bạn đã dùng định dạng OpenAI, bạn chỉ cần đổi base URL và model ID.

  • Base URL: https://qianfan.baidubce.com/v2
  • Model ID: ernie-5.1
  • Model preview: ernie-5.1-preview cho một số tính năng truy cập sớm

Request tối thiểu:

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
  }'
Enter fullscreen mode Exit fullscreen mode

Response có dạng tương thích 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
  }
}
Enter fullscreen mode Exit fullscreen mode

Cách xử lý lỗi nhanh:

  • 401 Unauthorized: khóa sai hoặc đã hết hạn.
  • 403: khóa hợp lệ nhưng workspace chưa bật model ERNIE 5.1. Vào console và thêm model vào danh sách được phép.

Bước 3: Gọi ERNIE 5.1 từ Python

Vì endpoint tương thích OpenAI, bạn có thể dùng SDK Python openai và chỉ cần đổi base_url.

Cài SDK nếu chưa có:

pip install openai
Enter fullscreen mode Exit fullscreen mode

Ví dụ gọi chat completion:

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}")
Enter fullscreen mode Exit fullscreen mode

Nếu bạn đã có wrapper quanh OpenAI SDK, thử nghiệm A/B với ERNIE 5.1 thường chỉ cần đổi base_url và model. Cách này cũng tương tự với API của DeepSeek và nhiều nhà cung cấp mô hình Trung Quốc khác.

Bước 4: Streaming token cho giao diện chat

Với UI chat, nên bật streaming để người dùng thấy phản hồi ngay khi model sinh token.

Trong Python, đặt 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)
Enter fullscreen mode Exit fullscreen mode

Request curl tương đương để debug:

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
Enter fullscreen mode Exit fullscreen mode

Định dạng stream giống OpenAI: các dòng data: {...} và kết thúc bằng:

data: [DONE]
Enter fullscreen mode Exit fullscreen mode

Bước 5: Dùng ERNIE 5.1 với tool calling

ERNIE 5.1 được nhấn mạnh ở khả năng dùng công cụ. Theo thông tin ra mắt, mô hình đạt điểm cao hơn DeepSeek-V4-Pro trên τ³-bench và SpreadsheetBench-Verified, nghĩa là tool calling được tối ưu cho các tình huống thực tế hơn là chỉ demo.

Schema tool giống function calling của 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})")
Enter fullscreen mode Exit fullscreen mode

Sau khi code của bạn chạy công cụ thực tế, hãy nối kết quả vào messages dưới dạng message có role tool, rồi gọi lại model. Vòng lặp kết thúc khi:

finish_reason == "stop"
Enter fullscreen mode Exit fullscreen mode

và tool_calls rỗng.

Một điểm nên xử lý phòng ngừa: ERNIE 5.1 đôi khi trả về arguments của tool dưới dạng JSON được bọc trong code block thay vì chuỗi JSON thuần. Hãy parse bằng json.loads() trong try/except; nếu lỗi, loại bỏ phần

```json trước khi parse lại.

Ví dụ helper đơn giản:


python
import json
import re

def parse_tool_arguments(raw):
    try:
        return json.loads(raw)
    except json.JSONDecodeError:
        cleaned = re.sub(r"^

```json|```

$", "", raw.strip(), flags=re.MULTILINE).strip()
        return json.loads(cleaned)
Enter fullscreen mode Exit fullscreen mode

Bước 6: Gọi ERNIE 5.1 từ Node.js

Với dự án Node.js dùng openai v5+, cấu hình tương tự Python.

Cài package:


bash
npm install openai
Enter fullscreen mode Exit fullscreen mode

Ví dụ:


javascript
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);
Enter fullscreen mode Exit fullscreen mode

response_format: { type: "json_object" } hoạt động và đáng dùng khi bạn cần JSON. Tuy nhiên, JSON schema nghiêm ngặt (json_schema) vẫn đang được triển khai trên Qianfan, nên hãy validate response trong code thay vì chỉ dựa vào ràng buộc từ model.

Ví dụ validate tối thiểu:


javascript
const raw = completion.choices[0].message.content;

let data;
try {
  data = JSON.parse(raw);
} catch {
  throw new Error("Model did not return valid JSON");
}

if (!Array.isArray(data.tips)) {
  throw new Error("Invalid response shape: expected tips array");
}
Enter fullscreen mode Exit fullscreen mode

Bước 7: Kiểm thử và so sánh bằng Apidog

Nếu bạn đang so sánh ERNIE 5.1, DeepSeek V4 và Kimi K2.6, không nên quản lý mọi thứ bằng nhiều lệnh terminal rời rạc. Dùng Apidog để tạo một workspace duy nhất, mỗi nhà cung cấp là một thư mục, cùng body request và môi trường riêng cho từng API key.

Thiết lập trong khoảng 60 giây:

  1. Mở Apidog và tạo project mới tên “LLM bake-off.”

Tạo project trong Apidog

  1. Thêm environment với các biến:

text
QIANFAN_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
Enter fullscreen mode Exit fullscreen mode

Tạo environment trong Apidog

  1. Tạo ba request, mỗi request trỏ tới base URL của từng nhà cung cấp.
  2. Đặt model lần lượt là:

text
ernie-5.1
deepseek-chat
kimi-k2-6
Enter fullscreen mode Exit fullscreen mode
  1. Dùng cùng một mảng messages cho cả ba request.
  2. Dùng tính năng Run của Apidog để chạy song song và so sánh output.

Gói miễn phí đủ để làm việc này. Apidog lưu lịch sử request theo environment, nên bạn có thể quay lại tuần sau và chạy lại cùng một bài đánh giá với phiên bản model mới. Cách này dễ kiểm soát hơn nhiều so với việc giữ nhiều lệnh curl trong tmux.

Để xem thêm về kiểm thử đa nhà cung cấp, đọc Kiểm thử LLM cục bộ dưới dạng API và hướng dẫn API GLM 5.1.

Giá cả, giới hạn tốc độ và hạn mức

Giá công khai của Qianfan cho ERNIE 5.1 không có trong bài phát hành. Hãy kiểm tra bảng giá trực tiếp trong console trước khi báo cáo số liệu nội bộ.

Ba điểm thực tế cần xử lý trong quá trình tích hợp:

  • Rate limit áp dụng theo workspace. Tài khoản mới thường có QPS thấp. Sau khi thử nghiệm xong, hãy nâng giới hạn trong console nếu cần production traffic.
  • Token usage có trong response. Trường usage gồm prompt_tokens, completion_tokens và total_tokens. Hãy log các giá trị này cho từng request để tự tính chi phí.
  • Không có prompt caching tự động. Qianfan hiện không cung cấp cơ chế lưu prompt gốc cho ERNIE 5.1 như Anthropic. Nếu system prompt dài 2.000 token, bạn sẽ trả phí cho phần đó ở mỗi lần gọi. Hãy thiết kế prompt và context window cho phù hợp.

Ví dụ log token usage:


python
response = client.chat.completions.create(
    model="ernie-5.1",
    messages=messages,
)

usage = response.usage

print({
    "prompt_tokens": usage.prompt_tokens,
    "completion_tokens": usage.completion_tokens,
    "total_tokens": usage.total_tokens,
})
Enter fullscreen mode Exit fullscreen mode

Xử lý lỗi thường gặp

Các lỗi bạn sẽ gặp trong thực tế:

Trạng thái Ý nghĩa Cách khắc phục
401 Bearer token sai hoặc đã hết hạn Tạo lại khóa từ console
403 Model chưa được bật cho workspace Thêm ERNIE 5.1 trong console
429 Đạt giới hạn tốc độ Dừng lại và retry với jitter
400 Message không hợp lệ Kiểm tra thứ tự role user/assistant
500/502 Lỗi tạm thời phía Qianfan Retry một lần; nếu tiếp diễn, kiểm tra trang trạng thái

Mọi lời gọi production nên có retry với exponential backoff, giới hạn tối đa 3 lần. Nếu chạy production, hãy ghi lại request_id từ response headers; bộ phận hỗ trợ của Baidu cần giá trị này khi debug.

Wrapper Python tối thiểu cho production

Nếu muốn đưa ERNIE 5.1 vào ứng dụng ngay, đây là wrapper nhỏ gọn để xử lý phần lớn tình huống phổ biến:


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:
            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")
Enter fullscreen mode Exit fullscreen mode

Dùng wrapper:


python
messages = [
    {"role": "system", "content": "You are a concise API assistant."},
    {"role": "user", "content": "Design a pagination scheme for a REST API."},
]

response = chat(messages)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Wrapper này xử lý phần retry cơ bản. Với streaming và tool calling, hãy mở rộng từ cùng cấu trúc này.

Câu hỏi thường gặp

API ERNIE 5.1 có miễn phí không?

Không. Qianfan hoạt động theo mô hình trả tiền theo mức sử dụng. Không có gói miễn phí vĩnh viễn; tài khoản mới đôi khi nhận được credit thử nghiệm. Nếu muốn thử miễn phí, dùng giao diện chat tại ernie.baidu.com hoặc xem các tùy chọn LLM miễn phí.

Tôi có thể chạy ERNIE 5.1 cục bộ không?

Không. Không có trọng số công khai. Nếu bắt buộc triển khai tại chỗ, hãy xem cách chạy DeepSeek V4 cục bộ hoặc các LLM cục bộ tốt nhất năm 2026.

OpenAI SDK có hoạt động mà không cần sửa nhiều không?

Có. Đặt base_url thành https://qianfan.baidubce.com/v2 và api_key thành khóa Qianfan. Trường model dùng ID model của Qianfan, không phải OpenAI. Function calling, streaming và response_format: json_object đều hoạt động. Xác thực json_schema nghiêm ngặt vẫn đang được triển khai.

ERNIE 5.1 xử lý prompt tiếng Trung và tiếng Anh như thế nào?

Cả hai đều là ưu tiên chính. Điểm Arena Search 1.223 đến từ nhóm bình chọn đa ngôn ngữ. Với tác vụ kỹ thuật tiếng Anh như code và thiết kế API, mô hình cạnh tranh với các model tiên tiến. Với viết sáng tạo tiếng Trung, nó là một trong những model Trung Quốc mạnh nhất.

Chiều dài output tối đa là bao nhiêu?

Chưa được công bố chính thức. Trong thực tế, response đơn lượt thường giới hạn khoảng 8K token trước khi model kết thúc. Với tác vụ tạo văn bản dài, hãy chia nhỏ nội dung và tiếp tục theo từng phần.

Nếu bạn đang xây dựng tác nhân trên ERNIE 5.1, hãy tải Apidog và dùng bộ request tương thích OpenAI để mock, kiểm thử và tài liệu hóa endpoint Qianfan cùng các service còn lại.

Top comments (0)