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

ERNIE 5.1 ra mắt vào ngày 9 tháng 5 năm 2026, và trong vòng một tuần, API Qianfan đã sẵn sàng cho nó. Nếu bạn muốn gọi mô hình từ mã của mình, định tuyến các lệnh gọi công cụ qua nó, hoặc tích hợp nó vào một vòng lặp tác nhân với Apidog, hướng dẫn này sẽ chỉ dẫn toàn bộ quá trình: tài khoản, khóa, phần thân yêu cầu, truyền trực tuyến, sử dụng công cụ, xử lý lỗi.

Chúng ta sẽ đi vào thực tế. Đến cuối cùng, bạn sẽ có các đoạn mã curl, Python và Node hoạt động, cùng với một bộ sưu tập yêu cầu mà bạn có thể đưa vào Apidog.

Nếu bạn chưa đọc bài phân tích ra mắt ERNIE 5.1, hãy đọc lướt qua trước; nó bao gồm các điểm chuẩn và so sánh với DeepSeek V4 và Kimi K2.6. Bài đăng này là phần hướng dẫn triển khai đi kèm.

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

ERNIE 5.1 được cung cấp thông qua nền tảng Qianfan của Baidu Intelligent Cloud. Không có “API ERNIE” riêng biệt; mọi thứ đều được định tuyến qua Qianfan.

Truy cập cloud.baidu.com và tạo hoặc đăng nhập vào tài khoản Baidu Intelligent Cloud. Các nhà phát triển quốc tế có thể sử dụng đăng ký qua email; một số tính năng doanh nghiệp vẫn yêu cầu số điện thoại di động Trung Quốc đại lục.
Mở bảng điều khiển Qianfan tại console.bce.baidu.com/qianfan.
Trong phần **Quản lý khóa API** (`API Key 管理`), nhấp vào **Tạo khóa API**. Chọn không gian làm việc và cấp quyền truy cập vào dịch vụ chat-completions.
Sao chép khóa. Nó có dạng bce-v3/ALTAK-xxxx/xxxx. Lưu trữ nó trong một biến môi trường, không phải trong mã nguồn.

export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"

Hai điều cần biết trước. Thứ nhất, điểm cuối v2 mới sử dụng một mã thông báo Bearer duy nhất; quy trình `access_token` OAuth v1 cũ đang bị loại bỏ và bạn không nên xây dựng mã mới dựa trên nó. Thứ hai, ERNIE 5.1 là một mô hình trả phí ngay từ đầu. Hãy nạp một số dư nhỏ (¥10 là đủ để thử nghiệm) trước yêu cầu đầu tiên của bạn.

Bước 2: Gửi yêu cầu đến điểm cuối tương thích OpenAI bằng curl

Qianfan cung cấp một điểm cuối chat-completions tương thích với OpenAI, vì vậy bất kỳ thành phần nào trong hệ thống của bạn đã hiểu định dạng của OpenAI đều sẽ hoạt động chỉ bằng cách thay đổi URL cơ sở và ID mô hình.

URL cơ sở: https://qianfan.baidubce.com/v2 ID mô hình: ernie-5.1 (hoặc: ernie-5.1-preview cho các tính năng truy cập sớm)

Yêu cầu tối thiểu hoạt động được:

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
  }'

Bạn sẽ nhận được một phản hồi theo định dạng OpenAI tiêu chuẩn:

{
  "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
  }
}

Nếu bạn thấy lỗi 401 Unauthorized, khóa của bạn không chính xác hoặc đã hết hạn. Nếu bạn thấy lỗi 403, khóa hợp lệ nhưng mô hình không được bật trên không gian làm việc này; hãy quay lại bảng điều khiển và thêm ERNIE 5.1 vào các mô hình được phép của không gian làm việc.

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

Vì điểm cuối tương thích với OpenAI, SDK Python chính thức của openai hoạt động nguyên trạng. Chỉ cần trỏ nó đến 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}")

Nếu bạn đã có các trình bao bọc xung quanh OpenAI SDK trong mã nguồn của mình, việc thay thế ERNIE 5.1 để thử nghiệm A/B chỉ cần thay đổi một dòng. Phương pháp tương tự cũng hoạt động với API của DeepSeek và hầu hết các nhà cung cấp mô hình Trung Quốc khác.

Bước 4: Truyền trực tuyến các token cho giao diện người dùng kiểu trò chuyện

Đối với bất kỳ cuộc trò chuyện hướng người dùng nào, bạn sẽ muốn truyền trực tuyến. Đặt stream: true và tiêu thụ các sự kiện được gửi từ máy chủ.

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)

Lệnh curl tương đương để gỡ lỗi:

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

Định dạng stream giống hệt của OpenAI: các dòng data: {...} được kết thúc bằng data: [DONE].

Bước 5: Sử dụng ERNIE 5.1 với các công cụ (phần tác nhân)

Đây là điểm mà ERNIE 5.1 tạo nên tiêu đề ra mắt của nó. Mô hình đạt điểm cao hơn DeepSeek-V4-Pro trên τ³-bench và SpreadsheetBench-Verified, điều này có nghĩa là việc gọi công cụ hoạt động trong môi trường thực tế, không chỉ trong các bản demo.

Cùng một lược đồ với việc gọi hàm 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})")

Sau khi mã của bạn chạy công cụ thực tế, hãy nối kết quả dưới dạng tin nhắn vai trò công cụ và gọi lại. Vòng lặp sẽ kết thúc khi finish_reason == "stop" và tool_calls trống.

Một điểm cần lưu ý: ERNIE 5.1 đôi khi trả về các đối số công cụ dưới dạng JSON được chuyển đổi thành chuỗi bên trong một khối mã thay vì dưới dạng một chuỗi JSON rõ ràng. Hãy phân tích cú pháp một cách phòng ngừa bằng json.loads() được bao trong try/except, và nếu thất bại, hãy loại bỏ các dấu ```json trước khi thử lại.

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

Sử dụng dễ dàng cho bất kỳ dự án Node nào sử dụng openai v5+:

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" } hoạt động và đáng tin cậy. Các lược đồ JSON nghiêm ngặt (`json_schema`) vẫn đang được triển khai trên Qianfan; hãy xác minh hình dạng phản hồi trong mã thay vì tin tưởng vào ràng buộc.

Bước 7: Kiểm tra và so sánh với Apidog

Nếu bạn đang phân vân giữa ERNIE 5.1, DeepSeek V4 và Kimi K2.6, đừng thực hiện việc đó từ terminal. Hãy sử dụng Apidog để xây dựng một không gian làm việc duy nhất với một thư mục cho mỗi nhà cung cấp, các phần thân yêu cầu giống hệt nhau và các môi trường được lưu cho mỗi khóa API.

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

Mở Apidog và tạo một dự án mới có tên “LLM bake-off.”

Thêm một môi trường với các biến QIANFAN_API_KEY, DEEPSEEK_API_KEY, MOONSHOT_API_KEY.

Tạo ba yêu cầu trỏ đến URL cơ sở của từng nhà cung cấp với model được đặt lần lượt là ernie-5.1, deepseek-chat, và kimi-k2-6.

Ghim cùng một mảng messages trên cả ba. Sử dụng tính năng “Run” của Apidog để chạy chúng song song và so sánh kết quả đầu ra.

Gói miễn phí xử lý việc này một cách dễ dàng. Apidog lưu trữ lịch sử yêu cầu cho mỗi môi trường, vì vậy bạn có thể quay lại vào tuần tới và chạy lại cùng một đánh giá chính xác với phiên bản mô hình mới. Tốt hơn nhiều so với việc theo dõi curl trong một khung tmux.

Để biết thêm về kiểm thử đa nhà cung cấp, hãy xem Kiểm thử LLM cục bộ dưới dạng API và hướng dẫn API GLM 5.1 của chúng tôi.

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 đăng phát hành; hãy kiểm tra biểu giá trên bảng điều khiển trực tiếp trước khi báo cáo số liệu nội bộ. Ba mẹo thực tế trong khi bạn chờ đợi:

Giới hạn tốc độ mặc định được áp dụng cho không gian làm việc. Các tài khoản mới bắt đầu với giới hạn QPS thấp. Hãy nâng nó từ bảng điều khiển sau khi bạn hoàn tất thử nghiệm.
Việc sử dụng token hiển thị trong phản hồi. Trường usage cung cấp prompt_tokens, completion_tokens, và total_tokens cho mỗi lần gọi. Hãy ghi lại những thông tin này cho mỗi yêu cầu; đừng chỉ tin vào bảng điều khiển để tính toán chi phí.
Bộ nhớ đệm không tự động. Không giống như Anthropic, Qianfan hiện không cung cấp tính năng lưu trữ lời nhắc gốc cho ERNIE 5.1. Nếu bạn có một lời nhắc hệ thống dài 2.000 token, bạn sẽ phải trả tiền cho nó mỗi lần gọi. Hãy thiết kế kiến trúc để xử lý vấn đề đó.

Xử lý lỗi sẽ giúp bạn

Các lỗi bạn sẽ gặp trong thực tế, theo thứ tự tần suất gần đúng:

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 từ bảng điều khiển
403	Mô hình không được bật trên không gian làm việc này	Thêm ERNIE 5.1 trong bảng điều khiển
429	Đã đạt giới hạn tốc độ	Dừng lại + thử lại với độ trễ ngẫu nhiên
400 (tin nhắn không hợp lệ)	Sai thứ tự vai trò tin nhắn	Đảm bảo luân phiên vai trò người dùng/trợ lý
500/502	Lỗi tạm thời từ phía Qianfan	Thử lại một lần; nếu vẫn tiếp diễn, kiểm tra trang trạng thái

Hãy bao bọc mọi lời gọi bằng cơ chế thử lại với thời gian chờ tăng dần theo cấp số nhân, giới hạn tối đa 3 lần thử. Đối với môi trường sản xuất, hãy ghi lại request_id từ các tiêu đề phản hồi; bộ phận hỗ trợ của Baidu cần nó để gỡ lỗi trường hợp của bạn.

Một trình bao bọc tối thiểu theo định dạng sản phẩm

Nếu bạn muốn đưa ERNIE 5.1 vào một ứng dụng thực tế ngay hôm nay, đây là trình bao bọc nhỏ nhất mà không gây khó chịu:

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")

Điều đó xử lý 80% trường hợp. Đối với các vòng lặp công cụ và streaming, hãy xây dựng dựa trên nó.

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; các tài khoản mới đôi khi nhận được tín dụng dùng thử. Để thử nghiệm miễn phí, hãy sử dụng giao diện trò chuyện ernie.baidu.com hoặc xem xét 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 yêu cầu triển khai tại chỗ là bắt buộc, hãy xem cách chạy DeepSeek V4 cục bộ hoặc các LLM cục bộ tốt nhất vào năm 2026 thay thế.

OpenAI SDK có hoạt động mà không cần thay đổi không? Có, với base_url được đặt thành https://qianfan.baidubce.com/v2 và api_key được đặt thành khóa Qianfan của bạn. Trường model nhận ID mô hình của Qianfan, không phải của OpenAI. Gọi hàm, 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ý các lời nhắc tiếng Trung so với tiếng Anh như thế nào? Cả hai đều được ưu tiên hàng đầu. Điểm Arena Search là 1.223 đến từ một nhóm người bình chọn đa ngôn ngữ. Đối với các tác vụ kỹ thuật tiếng Anh (mã, thiết kế API), nó cạnh tranh với các mô hình tiên tiến nhất; đối với viết sáng tạo tiếng Trung, nó là tốt nhất trong số các mô hình Trung Quốc.

Chiều dài đầu ra tối đa là bao nhiêu? Không được công bố chính thức. Trong thực tế, các phản hồi đơn lượt giới hạn khoảng 8K token trước khi mô hình kết thúc. Đối với tạo văn bản dài, hãy chia nhỏ và tiếp tục.

Đang xây dựng một tác nhân trên ERNIE 5.1? Tải xuống Apidog và sử dụng bộ sưu tập yêu cầu tương thích với OpenAI để tạo mock, kiểm thử và tài liệu hóa điểm cuối Qianfan cùng với các dịch vụ còn lại của bạn.