Chuyển đổi từ OpenAI sang RouteAPI

Hướng dẫn này giúp bạn chuyển đổi các ứng dụng OpenAI hiện có sang RouteAPI. Trong hầu hết các trường hợp, bạn chỉ cần thay đổi Base URL và API Key, phần còn lại của code giữ nguyên.

Tại sao nên chuyển sang RouteAPI

RouteAPI cung cấp nhiều khả năng hơn trong khi vẫn duy trì khả năng tương thích với OpenAI:

Truy cập thống nhất đa nhà cung cấp - Sử dụng Claude, Gemini, Azure, AWS Bedrock và nhiều model khác ngoài OpenAI mà không cần thay đổi code
Quản lý chi phí & kiểm soát ngân sách - Quản lý tập trung việc sử dụng và hạn ngạch cho nhiều model để tránh chi tiêu quá mức
Khả năng quan sát nâng cao - Nhật ký yêu cầu thống nhất, thống kê sử dụng và giám sát hiệu suất
Tính khả dụng cao & cân bằng tải - Chuyển đổi tự động khi có lỗi và phân phối tải đa kênh
Quyền hạn & hạn ngạch linh hoạt - Tạo token và giới hạn độc lập cho các đội, dự án hoặc môi trường khác nhau

Đánh giá độ khó chuyển đổi

Kịch bản	Thay đổi cần thiết	Thời gian ước tính
Sử dụng OpenAI SDK (Python/Node.js)	Chỉ sửa cấu hình khởi tạo (2 dòng code)	< 5 phút
Sử dụng framework như LangChain/LiteLLM	Sửa các tham số cấu hình	< 10 phút
Sử dụng client như Cursor/Claude Code	Cập nhật Base URL và Key trong cài đặt	< 5 phút
Yêu cầu HTTP trực tiếp	Sửa URL yêu cầu và header xác thực	< 10 phút

Thay đổi cấu hình cơ bản

Các bước chính của việc chuyển đổi liên quan đến việc sửa đổi hai mục cấu hình:

1. Thay đổi Base URL

Thay thế Base URL của OpenAI bằng RouteAPI:

# URL OpenAI gốc
https://api.openai.com/v1

# URL RouteAPI
https://api.routeapi.ai/v1

2. Thay thế API Key

Sử dụng token RouteAPI thay vì API Key của OpenAI:

Đăng nhập vào RouteAPI Console
Tạo token mới trên trang API Keys
Sao chép và lưu token (định dạng: sk-...)

3. Quản lý biến môi trường

Khuyến nghị quản lý thông tin xác thực bằng biến môi trường:

# File .env
ROUTEAPI_KEY=sk-your-routeapi-token

Mẹo bảo mật: Không commit token vào hệ thống quản lý phiên bản. Sử dụng .gitignore để loại trừ file .env.

Chuyển đổi Python SDK

OpenAI SDK

Chỉ sửa các tham số base_url và api_key:

# Trước khi chuyển đổi - OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-proj-...",  # OpenAI Key
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
)

# Sau khi chuyển đổi - RouteAPI
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],  # Sử dụng token RouteAPI
    base_url="https://api.routeapi.ai/v1",  # Trỏ đến RouteAPI
)

response = client.chat.completions.create(
    model="gpt-4",  # Hoặc sử dụng model khác như claude-3-5-sonnet-20241022
    messages=[{"role": "user", "content": "Hello"}],
)

Các thay đổi:

Thêm tham số base_url
Thay thế api_key, nên đọc từ biến môi trường
Tùy chọn: Thay đổi model sang các model khác được hỗ trợ bởi RouteAPI

Cấu hình LangChain

# Trước khi chuyển đổi
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key="sk-proj-...",
)

# Sau khi chuyển đổi
from langchain_openai import ChatOpenAI
import os

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

Cấu hình LiteLLM

# Trước khi chuyển đổi
import litellm

response = litellm.completion(
    model="gpt-4",
    api_key="sk-proj-...",
    messages=[{"role": "user", "content": "Hello"}],
)

# Sau khi chuyển đổi
import litellm
import os

response = litellm.completion(
    model="gpt-4",
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
    messages=[{"role": "user", "content": "Hello"}],
)

Chuyển đổi Node.js SDK

OpenAI SDK

Chỉ sửa cấu hình khởi tạo:

// Trước khi chuyển đổi - OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-proj-...',  // OpenAI Key
});

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
});

// Sau khi chuyển đổi - RouteAPI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,  // Sử dụng token RouteAPI
  baseURL: 'https://api.routeapi.ai/v1',  // Trỏ đến RouteAPI
});

const response = await client.chat.completions.create({
  model: 'gpt-4',  // Hoặc sử dụng model khác như claude-3-5-sonnet-20241022
  messages: [{ role: 'user', content: 'Hello' }],
});

Các thay đổi:

Thêm tham số baseURL
Thay thế apiKey, nên đọc từ biến môi trường
Tùy chọn: Thay đổi model sang các model khác được hỗ trợ bởi RouteAPI

Chuyển đổi công cụ client

Nếu bạn đang sử dụng IDE client hoặc coding agent, chỉ cần cập nhật cấu hình trong bảng cài đặt:

Client	Hướng dẫn cấu hình
Cursor	Cấu hình Cursor
Claude Code	Cấu hình Claude Code
OpenCode	Cấu hình OpenCode
Codex (oh-my-codex)	Cấu hình Codex

Thường bạn chỉ cần sửa hai mục:

Base URL / API Endpoint → https://api.routeapi.ai/v1
API Key → Token RouteAPI của bạn

Kiểm tra tương thích tham số

Các tham số không thay đổi

Các tham số sau hoạt động giống hệt trong RouteAPI như trong OpenAI:

model - ID model
messages - Mảng tin nhắn hội thoại
temperature - Kiểm soát tính ngẫu nhiên (0-2)
max_tokens - Số token tối đa để tạo
top_p - Tham số nucleus sampling
frequency_penalty - Phạt tần suất
presence_penalty - Phạt hiện diện
stop - Chuỗi dừng
stream - Có bật phản hồi streaming hay không
user - Định danh người dùng cuối
n - Số lượng completion trả về

Các tham số cần lưu ý

Hỗ trợ cho một số tham số phụ thuộc vào khả năng của model được chọn:

Tham số	Mô tả	Phụ thuộc
`tools` / `tool_choice`	Gọi công cụ (Function Calling)	Model phải hỗ trợ gọi công cụ
`response_format`	Đầu ra có cấu trúc (chế độ JSON)	Model phải hỗ trợ đầu ra JSON
`seed`	Seed sampling xác định	Được hỗ trợ bởi một số model
`logprobs` / `top_logprobs`	Trả về xác suất token	Được hỗ trợ bởi một số model

Khuyến nghị: Đối với các tham số nâng cao, hãy kiểm tra trong môi trường test trước để xác minh model hỗ trợ.

Xử lý giá trị zero rõ ràng

RouteAPI tuân theo quy ước Rule 5:

Nếu client truyền rõ ràng temperature=0, top_p=0 hoặc max_tokens=0, các giá trị này được chuyển tiếp nguyên vẹn đến model upstream
Chúng không bị coi là “chưa đặt” và bị bỏ qua

Điều này có nghĩa là bạn có thể tự tin sử dụng temperature=0 để có đầu ra xác định.

Tên model

Truy vấn các model có sẵn

Sau khi chuyển đổi, bạn có thể truy cập nhiều model hơn ngoài OpenAI. Sử dụng endpoint /v1/models để truy vấn:

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Ví dụ phản hồi:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1677610602,
      "owned_by": "anthropic"
    },
    {
      "id": "gemini-2.0-flash-exp",
      "object": "model",
      "created": 1677610602,
      "owned_by": "google"
    }
    // ...nhiều model hơn
  ]
}

Sử dụng ID model

Quan trọng: Sử dụng trường id của model trong yêu cầu (ví dụ: claude-3-5-sonnet-20241022), không phải tên hiển thị (ví dụ: “Claude 3.5 Sonnet”).

# ✅ Đúng - Sử dụng ID model
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[...],
)

# ❌ Sai - Sử dụng tên hiển thị
response = client.chat.completions.create(
    model="Claude 3.5 Sonnet",  # Sẽ gây lỗi
    messages=[...],
)

Chuyển đổi model giữa các nhà cung cấp

Sau khi chuyển sang RouteAPI, bạn có thể dễ dàng thử các model từ các nhà cung cấp khác nhau:

# Model OpenAI
model="gpt-4"
model="gpt-4o"

# Model Anthropic Claude
model="claude-3-5-sonnet-20241022"
model="claude-3-5-haiku-20241022"

# Model Google Gemini
model="gemini-2.0-flash-exp"
model="gemini-1.5-pro-002"

# Model AWS Bedrock (qua RouteAPI)
model="anthropic.claude-3-5-sonnet-20241022-v2:0"

Chỉ cần sửa tham số model, không cần thay đổi code khác.

Kiểm thử và xác thực

Danh sách kiểm tra

Sau khi chuyển đổi, khuyến nghị xác thực bằng danh sách kiểm tra sau:

Kiểm tra xác thực - Xác nhận token hợp lệ và có thể gọi /v1/models thành công
Gọi cơ bản - Kiểm tra chat.completions.create trả về bình thường
Phản hồi streaming - Nếu sử dụng stream=True, xác minh đầu ra streaming hoạt động
Gọi công cụ - Nếu sử dụng Function Calling, xác minh luồng gọi công cụ
Xử lý lỗi - Kiểm tra các kịch bản lỗi như số dư không đủ, giới hạn tốc độ, tham số không hợp lệ
Thống kê sử dụng - Kiểm tra trong console RouteAPI nhật ký sử dụng được ghi chính xác

Khắc phục sự cố thường gặp

Mã lỗi	Nguyên nhân thường gặp	Giải pháp
401 Unauthorized	Token không hợp lệ hoặc thiếu	Kiểm tra định dạng header `Authorization`: `Bearer sk-...`
402 Payment Required	Số dư không đủ hoặc hạn ngạch cạn kiệt	Đăng nhập console để nạp tiền hoặc tăng hạn ngạch token
404 Not Found	Base URL sai hoặc lỗi chính tả trong đường dẫn	Xác nhận Base URL là `https://api.routeapi.ai/v1`
429 Too Many Requests	Đạt giới hạn tốc độ	Giảm tần suất yêu cầu hoặc liên hệ admin để tăng giới hạn
500 Internal Server Error	Sự cố dịch vụ model upstream	Thử lại yêu cầu hoặc chuyển sang model dự phòng

Mẹo debug:

Sử dụng cURL để kiểm tra API trực tiếp, loại trừ vấn đề cấu hình SDK
Kiểm tra nhật ký sử dụng console RouteAPI để biết thông báo lỗi cụ thể
So sánh sự khác biệt tham số giữa yêu cầu OpenAI gốc và yêu cầu RouteAPI

Ví dụ: Kiểm tra bằng cURL

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Nếu yêu cầu cURL thành công, cấu hình token và Base URL đúng, và vấn đề có thể ở lớp SDK.

Khuyến nghị chuyển đổi từng bước

Đối với môi trường production, chiến lược chuyển đổi dần dần được khuyến nghị:

1. Xác thực trong môi trường test trước

Kiểm thử đầy đủ code đã chuyển đổi trong môi trường development hoặc test
Xác minh chức năng cốt lõi, các trường hợp biên và xử lý lỗi
So sánh nội dung phản hồi và hiệu suất giữa OpenAI và RouteAPI

2. Triển khai dần dần

Sử dụng feature flag để kiểm soát việc chuyển đổi Base URL
Kích hoạt RouteAPI cho một phần trăm nhỏ lưu lượng trước
Quan sát tỷ lệ lỗi, độ trễ và phản hồi người dùng

Ví dụ: Kiểm soát bằng biến môi trường

import os

# Kiểm soát có sử dụng RouteAPI hay không qua biến môi trường
USE_ROUTEAPI = os.getenv("USE_ROUTEAPI", "false").lower() == "true"

if USE_ROUTEAPI:
    base_url = "https://api.routeapi.ai/v1"
    api_key = os.environ["ROUTEAPI_KEY"]
else:
    base_url = "https://api.openai.com/v1"
    api_key = os.environ["OPENAI_API_KEY"]

client = OpenAI(api_key=api_key, base_url=base_url)

3. Giám sát nhật ký sử dụng và tỷ lệ lỗi

Sau khi chuyển đổi, theo dõi chặt chẽ:

Tỷ lệ yêu cầu thành công - Kiểm tra các lỗi 4xx/5xx bất thường
Độ trễ phản hồi - Phân bố độ trễ P50, P95, P99
Sử dụng token - Xác minh thanh toán phù hợp với kỳ vọng
Tính khả dụng của model - Tỷ lệ thành công và độ trễ cho các model khác nhau

Các bản ghi chi tiết có sẵn trên trang “Nhật ký sử dụng” trong console RouteAPI.

4. Kế hoạch rollback

Chuẩn bị kế hoạch rollback nhanh về OpenAI:

Giữ API Key OpenAI gốc, đừng xóa ngay lập tức
Sử dụng trung tâm cấu hình hoặc biến môi trường để quản lý Base URL cho việc chuyển đổi nhanh
Đặt ngưỡng cảnh báo trong giám sát để tự động kích hoạt rollback

# Ví dụ rollback: Chuyển đổi bằng cách sửa biến môi trường
# USE_ROUTEAPI=false -> Sử dụng OpenAI
# USE_ROUTEAPI=true -> Sử dụng RouteAPI

Khuyến nghị tối ưu hóa sau chuyển đổi

1. Tận dụng khả năng đa model

RouteAPI hỗ trợ model từ nhiều nhà cung cấp. Chọn model phù hợp nhất cho từng kịch bản:

Kịch bản nhạy cảm về độ trễ - Sử dụng gemini-2.0-flash-exp hoặc gpt-4o-mini
Tác vụ suy luận phức tạp - Sử dụng claude-3-5-sonnet-20241022 hoặc gpt-4
Tối ưu chi phí - So sánh hiệu quả chi phí của các model khác nhau và chọn giải pháp tối ưu

2. Thiết lập token độc lập

Tạo token riêng biệt cho các dự án, môi trường hoặc đội khác nhau:

Môi trường development - Token hạn ngạch thấp để tránh chi phí thử nghiệm quá mức
Môi trường production - Token hạn ngạch cao với cảnh báo được cấu hình
Các đội khác nhau - Token độc lập để gán chi phí và kiểm toán

3. Bật nhật ký yêu cầu

Xem nhật ký yêu cầu chi tiết trong console RouteAPI:

Model, sử dụng token và độ trễ cho mỗi yêu cầu
Nguyên nhân lỗi và stack trace cho các yêu cầu thất bại
Xu hướng sử dụng và phân tích chi phí

Các nhật ký này giúp tối ưu hóa chi phí và khắc phục sự cố.

Nhận trợ giúp

Nếu bạn gặp vấn đề trong quá trình chuyển đổi:

Xem lại Tài liệu tham khảo API
Truy cập RouteAPI Console để kiểm tra nhật ký sử dụng
Liên hệ hỗ trợ kỹ thuật để được trợ giúp

Tài liệu liên quan: