API OpenAI dành cho nhà phát triển: Sử dụng endpoint tương thích

Tóm tắt ngắn

Hầu hết hướng dẫn về API OpenAI cho nhà phát triển giả định một nhà cung cấp và một hóa đơn. Tuy nhiên, định dạng truyền tải chỉ là JSON qua HTTPS, và nhiều mã client, framework và công cụ có thể giao tiếp với bất kỳ máy chủ nào triển khai nó. Trang web này lưu trữ một máy chủ như vậy. Bạn giữ SDK của mình, thay đổi base URL, thay thế bằng khóa từ trang web này và đặt mô hình thành uncensored.

Đó là toàn bộ quá trình di chuyển cho một ứng dụng điển hình. Đây là danh sách kiểm tra, và phần còn lại của trang sẽ điền vào từng bước.

1. Tạo tài khoản và nhận tín dụng dùng thử trên trang khóa API.
2. Đặt base URL thành https://api.openaigatewayapi.com/v1.
3. Gửi khóa dưới dạng Authorization: Bearer <key>. Các SDK làm điều này cho bạn khi bạn truyền api_key.
4. Sử dụng uncensored làm ID mô hình trong mọi yêu cầu.
5. Xử lý HTTP 429 bằng cách thử lại với độ trễ ngắn, như được hiển thị gần cuối.

Có hai endpoint: POST /v1/chat/completions và GET /v1/models. Dịch vụ chỉ dành cho văn bản. Không có tạo hình ảnh hoặc âm thanh, không có embedding và không có fine-tuning, vì vậy nếu ứng dụng của bạn gọi những thứ đó, chúng sẽ cần một nhà cung cấp khác.

Kiểm tra kết nối với curl

Trước khi chạm vào ứng dụng của bạn, hãy xác nhận rằng khóa hoạt động. Endpoint mô hình là bài kiểm tra rẻ nhất vì nó không tạo ra token nào.

Copyexport API_KEY="paste-your-key-here"

curl https://api.openaigatewayapi.com/v1/models \
  -H "Authorization: Bearer $API_KEY" | grep -o uncensored

Lệnh grep in ra ID mô hình uncensored nếu danh sách chứa nó; bỏ grep để xem danh sách JSON đầy đủ. Nếu bạn nhận được 401, khóa sai hoặc thiếu tiền tố Bearer. Bây giờ hãy gửi một yêu cầu thực:

Copycurl https://api.openaigatewayapi.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain idempotency keys in two sentences."}
    ],
    "temperature": 0.4
  }'

Phản hồi mang các đối tượng choices và usage thông thường. Nó cũng bao gồm các tiêu đề đáng để ghi lại: X-Request-Id cho các câu hỏi hỗ trợ, X-Balance-USD cho tín dụng còn lại của bạn và hai tiêu đề X-RateLimit-Limit-* cho thấy giới hạn yêu cầu và độ đồng thời của bạn.

Python với gói openai chính thức

Trong Python, bạn chỉ cần chạm vào hàm tạo client. Mọi thứ sau đó là mã bạn đã có.

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short, accurate release notes."},
        {"role": "user", "content": "Summarise: added retry logic, fixed timeout bug."},
    ],
    temperature=0.5,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Đọc khóa từ biến môi trường trong mã thực tế. Mẫu mã khóa cứng khóa này chỉ để giữ đoạn mã ngắn gọn. max_tokens là tùy chọn ở đây; nếu bạn bỏ qua nó, phần hoàn thành có thể sử dụng bất kỳ token nào còn lại của cửa sổ 100.000 token (prompt cộng với phần hoàn thành cùng nhau). Đặt nó như một cách rẻ để giới hạn chi phí cho một quá trình sinh không kiểm soát.

Truyền phát

Truyền phát sử dụng Sự kiện gửi qua máy chủ và cùng cờ stream=True mà bạn biết. Số liệu sử dụng đến vào cuối luồng, vì vậy phần cuối cùng có thể có danh sách choices trống.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "List five edge cases for a date parser."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if getattr(chunk, "usage", None):
        print("\ntokens:", chunk.usage.total_tokens)

Một chi tiết quan trọng đối với lập kế hoạch dung lượng. Một yêu cầu streaming giữ slot đồng thời của nó cho đến khi luồng kết thúc, không phải cho đến khi token đầu tiên. Nếu một client từ bỏ một luồng mà không đóng nó, slot đó sẽ bận lâu hơn bạn mong đợi.

Ví dụ Node.js

SDK Node lấy hai cài đặt tương tự dưới các tên khác nhau.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.openaigatewayapi.com/v1",
  apiKey: process.env.GATEWAY_KEY,
});

const completion = await client.chat.completions.create({
  model: "uncensored",
  messages: [
    { role: "user", content: "Write a regex that matches ISO 8601 dates, and explain it." },
  ],
  temperature: 0.3,
});

console.log(completion.choices[0].message.content);

Nếu bạn sử dụng một framework có tích hợp OpenAI riêng, hãy tìm một trường có tên base URL, API base hoặc endpoint trong cài đặt của nó. Dán cùng URL vào đó thường là tất cả những gì cần thiết. Các giao diện trò chuyện, framework agent và plugin trình soạn thảo chủ yếu tuân theo mẫu này. Các tham số lấy mẫu như temperature, top_p, stop, seed và các hình phạt tần suất và hiện diện được chuyển tiếp đến mô hình.

Gọi công cụ và chế độ JSON

Hai tính năng quyết định xem một mô hình có phù hợp với một ứng dụng thực tế hay không: gọi các hàm của bạn và trả về dữ liệu bạn có thể phân tích cú pháp. Cả hai đều được hỗ trợ.

Gọi hàm

Bạn khai báo công cụ với tools, tùy chọn buộc một lựa chọn với tool_choice và gửi kết quả lại dưới dạng thông báo với role: "tool". Các phản hồi được truyền phát cung cấp tool_calls theo từng phần, giống như định dạng tiêu chuẩn.

Copyimport json
from openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up the status of an order by its ID.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = {"order_id": args["order_id"], "status": "shipped"}  # your real lookup here
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

Luôn xác thực các đối số trước khi hành động dựa trên chúng. Mô hình tạo ra JSON phù hợp với lược đồ của bạn hầu hết thời gian, không phải mọi lúc, vì vậy hãy xử lý call.function.arguments như bất kỳ đầu vào không đáng tin cậy nào khác.

Chế độ JSON

Đối với các công việc trích xuất và phân loại, hãy yêu cầu một đối tượng JSON và cũng nói điều đó trong prompt. Đề cập đến JSON trong hướng dẫn mang lại kết quả tốt hơn là chỉ dựa vào cờ.

Copyfrom openai import OpenAI
import json

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON only: {\"sentiment\": string, \"topics\": [string]}."},
        {"role": "user", "content": "The docs are clear but the rate limits caught me off guard."},
    ],
)
data = json.loads(resp.choices[0].message.content)
print(data)

Giới hạn, lỗi và thử lại

Khóa đầy đủ cho phép 8 yêu cầu đang chạy và 300 yêu cầu mỗi phút. Khóa dùng thử cho phép 2 yêu cầu đang chạy và 60 yêu cầu mỗi phút. Kích thước tối đa của thân yêu cầu là 8 MB. Vượt quá giới hạn và bạn sẽ nhận được HTTP 429, và mã lỗi cho bạn biết giới hạn nào đã bị vượt qua.

Mã lỗi	Ý nghĩa	Những việc cần làm
rate_limited	Quá nhiều yêu cầu mỗi phút	Làm chậm nhà sản xuất hoặc phân bổ công việc trong phút
concurrency	Quá nhiều yêu cầu cùng một lúc	Giảm số lượng worker của bạn xuống 8 hoặc ít hơn, hoặc 2 trên khóa dùng thử
429 với Retry-After: 5	Quá tải tạm thời	Chờ số giây được chỉ định và thử lại

Các SDK đã thử lại một số lỗi. Thêm xử lý của riêng bạn cho 429 để một đợt tăng tải không làm sập công việc hàng loạt:

Copyimport time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
    max_retries=0,
)

def ask(prompt, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            wait = float(e.response.headers.get("retry-after", 2 ** i))
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

Các yêu cầu bị lỗi hoặc từ chối không bị tính phí, vì vậy một vòng lặp thử lại không làm hóa đơn của bạn tăng gấp đôi. Một semaphore có kích thước bằng giới hạn đồng thời của bạn là cách sạch nhất để ở dưới giới hạn trong mã không đồng bộ.

Di chuyển ứng dụng hiện có sang

Nếu bạn có một ứng dụng hoạt động, đừng mã hóa cứng các giá trị mới. Đặt base URL, khóa và tên mô hình trong các biến môi trường để bạn có thể chuyển đổi giữa các môi trường mà không cần triển khai. Điều đó cũng cho phép bạn chạy cùng bộ thử nghiệm trên hai backend và so sánh đầu ra bên cạnh nhau.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.openaigatewayapi.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def complete(messages, **kw):
    return client.chat.completions.create(model=MODEL, messages=messages, **kw)

Sau đó, thực hiện qua một quy trình di chuyển ngắn:

1. Chạy tập prompt hiện tại của bạn trên endpoint mới và đọc kết quả đầu ra của chính bạn. Các kiểm tra tự động bắt lỗi định dạng, không phải giọng điệu.
2. Kiểm tra xem bất kỳ mã nào phân tích JSON vẫn hoạt động với response_format được đặt, và giữ một cách dự phòng để loại bỏ văn bản lạ xung quanh đối tượng.
3. Đo số lượng token thực tế từ usage, vì một mô hình khác phân đoạn văn bản khác nhau và các ước tính cũ của bạn có thể bị sai.
4. Bạn hãy đặt kích thước nhóm worker của mình ở mức 8 hoặc ít hơn để giới hạn độ đồng thời không bao giờ là nguyên nhân đầu tiên gây lỗi khi tải cao.
5. Phát hành cho một phần nhỏ lưu lượng truy cập, theo dõi tỷ lệ 429 và nhật ký lỗi, sau đó mở rộng.

Các nhóm thường quên prompt hệ thống trong quá trình này. Các prompt được viết để khuyến khích một mô hình dễ từ chối hành xử thường chứa các dòng lảng tránh không cần thiết ở đây và có thể làm lộn xộn đầu ra. Đọc lại của bạn và cắt những gì không còn làm gì nữa.

Những điều cần biết trước khi chuyển đổi

Tương thích bao gồm định dạng yêu cầu và phản hồi. Nó không làm cho đây là API chính thức của bất kỳ nhà sản xuất mô hình nào. Dịch vụ chạy một mô hình trọng số mở, được lưu trữ bởi một nhà cung cấp độc lập và được tinh chỉnh để trả lời mà không có từ chối nội dung cho việc sử dụng người lớn hợp pháp. Nó không phải là một bộ định tuyến qua các nhà cung cấp, vì vậy bạn sẽ không tìm thấy menu của các mô hình khác phía sau nó. Nội dung khiêu dâm liên quan đến người chưa thành niên không được phép, và giới hạn đó không thể thay đổi.

Lên kế hoạch xung quanh ba sự khác biệt thực tế so với một nền tảng đa mô hình lớn:

• Một mô hình. ID là uncensored. Nếu mã của bạn chuyển đổi mô hình theo nhiệm vụ, hãy thu gọn điều đó thành một giá trị.
• Chỉ văn bản. Loại bỏ bất kỳ lệnh gọi hình ảnh, âm thanh hoặc embedding nào khỏi đường dẫn đến endpoint này.
• Hành vi prompt khác nhau. Một mô hình khác đọc hướng dẫn khác nhau, vì vậy hãy chạy lại các prompt và bài kiểm tra của bạn sau khi chuyển đổi. Siết chặt các prompt hệ thống nơi đầu ra bị lệch.

Các prompt không được sử dụng để huấn luyện. Để xem danh sách đầy đủ các tham số, hãy xem tài liệu API. Nếu bạn đang ước tính chi tiêu, trang giá cả liệt kê tỷ lệ trên mỗi token: $0.15 cho 1 triệu token đầu vào và $0.50 cho 1 triệu token đầu ra, được tính từ tín dụng trả trước không cần đăng ký. Nạp tiền từ $20 đến $500 và tín dụng không bao giờ hết hạn. Nếu bạn đang cân nhắc một lớp proxy phía trước nhiều dịch vụ, trang về cổng LLM sẽ giải thích khi nào phần di chuyển bổ sung này đáng giá.

Hướng dẫn khác

• API Gateway OpenAI được giải thích bằng ngôn ngữ đơn giản
• Giá API Gateway OpenAI: Ví dụ chi phí thực tế
• Cổng LLM: Phân tích Chi phí so với Độ phức tạp