Chat Completions với cURL trên nhiều mô hình AI

Bạn có thể tìm hiểu về một AI gateway nhiều hơn chỉ với một lệnh terminal đơn lẻ so với cả một danh sách tính năng dài. Nếu gateway thực sự tương thích OpenAI, thì cùng một yêu cầu curl phải hoạt động trên các họ mô hình được hỗ trợ, trong khi base URL, header ủy quyền, định dạng message và cách phân tích phản hồi vẫn ổn định.

Bài hướng dẫn này cho thấy mẫu triển khai thực tế với Flatkey: bắt đầu bằng một yêu cầu chat-completions, đưa tên mô hình vào một biến, và kiểm tra một vài họ mô hình hiện tại mà không cần viết lại tích hợp. Nội dung được thiết kế cho các nhà phát triển muốn xác thực một API từ terminal trước khi họ thêm SDK hoặc commit mã ứng dụng.

Lưu ý về lựa chọn mô hình: Danh mục mô hình thay đổi. Các ID mô hình bên dưới phản ánh tài liệu công khai của Flatkey được kiểm tra vào ngày 24 tháng 7 năm 2026. Hãy xác nhận dòng mô hình hiện tại và mức độ khả dụng trước khi dùng một ID trong môi trường production.

Yêu cầu cURL chat-completions hoạt động ngắn nhất

Tạo một khóa API Flatkey, export nó trong shell của bạn, và gửi một yêu cầu đến endpoint chat-completions tương thích OpenAI:

export FLATKEY_API_KEY="your-flatkey-api-key"

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Write a one-sentence product description for a waterproof daypack."
      }
    ]
  }'

Bốn phần là quan trọng:

Đối với các mô hình chat tương thích, trường chính bạn cần thay đổi là model.

Sử dụng cùng một cấu trúc cURL trên các họ mô hình

Đặt ID mô hình vào một biến shell để phần thân request không cần thay đổi:

export FLATKEY_API_KEY="your-flatkey-api-key"
export MODEL="gpt-4o-mini"

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"Return concise ecommerce copy.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"Write a product title for a lightweight waterproof daypack.\"
      }
    ],
    \"temperature\": 0.2
  }" | jq -r '.choices[0].message.content'

Bây giờ chạy lại lệnh với một ID mô hình khác đã được tài liệu hóa:

export MODEL="claude-sonnet-4-6"

export MODEL="gemini-2.5-flash"

export MODEL="deepseek-v3.1"

Yêu cầu vẫn sử dụng cùng endpoint, header, message, và bộ phân tích jq. Điểm mạnh vận hành của kiểu gọi ổn định này là: bạn có thể so sánh các nhóm mô hình được hỗ trợ mà không cần duy trì một script terminal riêng cho từng nhà cung cấp.

Lưu ý về chọn mô hình: Một dạng yêu cầu dùng chung không có nghĩa mọi mô hình đều hoạt động giống nhau. Các tham số được hỗ trợ, giới hạn ngữ cảnh, hành vi công cụ, hành vi an toàn, độ trễ và kiểu đầu ra có thể khác nhau. Hãy xem tính tương thích như một giao diện tích hợp đơn giản hơn, chứ không phải bằng chứng rằng các mô hình có thể thay thế lẫn nhau.

Chạy một vòng lặp kiểm thử nhỏ trên nhiều mô hình

Để so sánh nhanh trong terminal, hãy định nghĩa một danh sách ngắn và gửi cùng một prompt tới từng mô hình:

#!/usr/bin/env bash
set -euo pipefail

: "${FLATKEY_API_KEY:?Hãy đặt FLATKEY_API_KEY trước}"

MODELS=(
  "gpt-4o-mini"
  "claude-sonnet-4-6"
  "gemini-2.5-flash"
  "deepseek-v3.1"
)

PROMPT="Write three benefit-led bullet points for a waterproof commuter backpack."

for MODEL in "${MODELS[@]}"; do
  echo
  echo "=== $MODEL ==="

  jq -n \
    --arg model "$MODEL" \
    --arg prompt "$PROMPT" \
    '{
      model: $model,
      messages: [
        {role: "system", content: "You write concise ecommerce copy."},
        {role: "user", content: $prompt}
      ],
      temperature: 0.2
    }' |
  curl -sS https://router.flatkey.ai/v1/chat/completions \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -r '.choices[0].message.content // .error.message'
done

Việc dùng jq -n để tạo JSON an toàn hơn so với việc tự escape một chuỗi shell dài. Nó cũng giúp script dễ mở rộng với biến, các message bổ sung hoặc tham số tùy chọn.

Lưu script với tên compare-models.sh, cấp quyền thực thi, rồi chạy nó:

chmod +x compare-models.sh
./compare-models.sh

Nên so sánh gì trong đầu ra

Kiểm thử nhiều mô hình chỉ hữu ích khi prompt và phương pháp chấm điểm nhất quán. Với một tác vụ viết nội dung thương mại điện tử, hãy so sánh:

Thêm các trường thời gian của cURL khi độ trễ là yếu tố quan trọng:

curl -sS -o response.json \
  -w 'status=%{http_code} total=%{time_total}s\n' \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Write a five-word product tagline."}
    ]
  }'

jq . response.json

Điều này tách riêng các phép đo vận chuyển khỏi đầu ra của mô hình. Terminal in ra trạng thái HTTP và tổng thời gian yêu cầu, trong khi phản hồi JSON vẫn sẵn sàng để kiểm tra.

Lưu ý về lựa chọn mô hình: Đừng chọn mô hình sản xuất chỉ từ một phản hồi. Hãy chạy một bộ prompt đại diện, lặp lại các yêu cầu và chấm điểm đầu ra theo các yêu cầu quan trọng đối với ứng dụng của bạn.

Giữ yêu cầu có thể so sánh

Những thay đổi nhỏ trong prompt hoặc tham số có thể làm cho việc kiểm thử mô hình trở nên sai lệch. Hãy sử dụng các kiểm soát sau:

1. Giữ các messages giống hệt nhau. Đừng cải thiện prompt cho một mô hình mà không làm vậy với các mô hình khác.
2. Sử dụng cùng một temperature. Các giá trị thấp hơn thường giúp các lần chạy so sánh dễ xem xét hơn.
3. Lưu JSON thô. Lưu toàn bộ phản hồi, không chỉ phần văn bản đã hiển thị.
4. Ghi lại ID của mô hình. Tên hiển thị là chưa đủ chính xác cho các bài kiểm thử có thể tái lập.
5. Tách lỗi ra khỏi câu trả lời kém. Lỗi truyền tải hoặc lỗi khả dụng không phải là điểm chất lượng đầu ra.
6. Kiểm tra tình trạng khả dụng hiện tại. Một mô hình đã được tài liệu hóa vẫn có thể thay đổi trạng thái vận hành.

Thêm xử lý lỗi cơ bản

Sử dụng --fail-with-body để cURL thoát khi gặp lỗi HTTP nhưng vẫn giữ phần nội dung phản hồi:

HTTP_BODY=$(mktemp)

if ! curl --fail-with-body -sS \
  -o "$HTTP_BODY" \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Return the word ready."}
    ]
  }'; then
  jq -r '.error.message // "Request failed"' "$HTTP_BODY" >&2
  rm -f "$HTTP_BODY"
  exit 1
fi

jq -r '.choices[0].message.content' "$HTTP_BODY"
rm -f "$HTTP_BODY"

Trong mã ứng dụng, cũng hãy thêm thời gian chờ rõ ràng, thử lại có giới hạn cho các lỗi có thể thử lại, và ghi log mà không làm lộ khóa bí mật hoặc nội dung prompt nhạy cảm.

Chính sách lựa chọn mô hình thực tế

Chính sách đơn giản nhất là chọn theo khối lượng công việc thay vì theo tên nhà cung cấp:

Bắt đầu với mô hình nhỏ nhất có thể vượt qua ngưỡng chất lượng của bạn một cách đáng tin cậy. Nâng cấp lên mô hình mạnh hơn khi tác vụ đòi hỏi. Nếu bạn thêm định tuyến dự phòng, hãy kiểm thử phương án dự phòng với cùng hợp đồng phản hồi thay vì cho rằng nó có thể thay thế mô hình chính mà không cần thay đổi ứng dụng.

Bạn có thể xem quyền truy cập mô hình hiện tại và giá trên trang giá của Flatkey trước khi chọn các ID cho một bài kiểm thử sản xuất.

Khi nào chuyển từ cURL sang SDK

cURL lý tưởng để xác nhận nhanh bốn điều:

• khóa API hoạt động
• URL cơ sở là chính xác
• mô hình đã chọn chấp nhận yêu cầu
• dạng phản hồi khớp với trình phân tích của bạn

Chuyển sang SDK khi bạn cần các tiện ích streaming, logic thử lại có cấu trúc, phản hồi có kiểu, client tái sử dụng, hoặc khả năng quan sát ở cấp ứng dụng. Hãy giữ yêu cầu cURL thành công trong sổ tay vận hành của bạn: đó vẫn là cách nhanh nhất để tách biệt sự cố truy cập cổng kết nối khỏi sự cố cấu hình SDK.

Danh sách kiểm tra triển khai cuối cùng

• Xuất khóa API thay vì đặt trực tiếp trong script.
• Sử dụng https://router.flatkey.ai/v1 làm URL cơ sở.
• Gửi các yêu cầu chat tương thích tới /chat/completions.
• Đưa ID mô hình vào cấu hình.
• Xây dựng JSON bằng jq khi việc thoát ký tự trong shell trở nên phức tạp.
• Ghi nhận mã trạng thái HTTP, độ trễ, nội dung phản hồi và dữ liệu mức sử dụng.
• So sánh các mô hình với cùng một prompt và tham số.
• Xác minh tính sẵn có hiện tại của danh mục trước khi triển khai sản xuất.
• Thêm timeout, số lần thử lại có giới hạn và ghi log an toàn với bí mật trong mã ứng dụng.

Một yêu cầu cURL ổn định cho bạn một điểm khởi đầu rõ ràng. Khi nó hoạt động, việc thay đổi trường model biến yêu cầu đó thành một bộ kiểm thử thực tiễn cho nhiều họ mô hình AI—mà không cần thay đổi xác thực, URL cơ sở hay trình phân tích phản hồi mỗi lần.

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

Tôi có thể dùng cùng một yêu cầu cURL chat-completions cho mọi mô hình AI không?

Hãy dùng nó cho các mô hình mà Flatkey cung cấp thông qua tuyến chat-completions tương thích. Các phương thức khác hoặc các tính năng đặc thù giao thức có thể yêu cầu endpoint hoặc trường yêu cầu khác.

Trường tối thiểu cho một yêu cầu chat-completions là gì?

Với yêu cầu cơ bản, hãy cung cấp một model được hỗ trợ và một mảng messages. Bạn cũng cần header xác thực bearer và kiểu nội dung JSON.

Tại sao nên đặt tên mô hình trong biến môi trường?

Nó giữ cho cấu trúc yêu cầu ổn định, giảm lỗi chỉnh sửa và giúp các script dễ chạy hơn giữa các cấu hình staging, evaluation và production.

Tôi có nên dùng cURL trong production không?

cURL rất phù hợp cho việc xác minh, script và runbook. Hầu hết các ứng dụng production sẽ được लाभ từ SDK hoặc HTTP client có hỗ trợ rõ ràng về timeout, retry, telemetry và xử lý kiểu dữ liệu.

Làm thế nào để tôi chọn giữa các mô hình GPT, Claude, Gemini và DeepSeek?

Hãy chọn bằng một bộ đánh giá đại diện. So sánh khả năng làm theo chỉ dẫn, chất lượng đầu ra, độ trễ, mức sử dụng token, hành vi lỗi và các tính năng cụ thể mà khối lượng công việc của bạn yêu cầu. Xác nhận tình trạng khả dụng hiện tại trước khi triển khai.