API OpenAI cho LLM cục bộ: Chạy cục bộ, chuyển sang dịch vụ lưu trữ

Ý nghĩa của cụm từ

Mọi người sử dụng "API OpenAI cho LLM cục bộ" cho hai điều liên quan. Thứ nhất là mô hình ngôn ngữ bạn tự chạy trên máy tính xách tay hoặc máy chủ gia đình, lắng nghe trên cổng cục bộ và truyền tải dữ liệu theo định dạng chat OpenAI. Thứ hai là thói quen viết ứng dụng của bạn theo định dạng đó để mô hình phía sau có thể được thay thế.

Định dạng là một hợp đồng đơn giản. Ứng dụng của bạn gửi một thân JSON với tên model và danh sách messages, mỗi phần có vai trò system, user hoặc assistant. Máy chủ trả về một đối tượng JSON chứa tin nhắn được tạo, hoặc một luồng các đoạn nhỏ nếu bạn yêu cầu truyền phát. Các SDK chính thức cho Python và JavaScript bao bọc điều này, và chúng cho phép bạn ghi đè Base URL, đây là điểm mấu chốt.

Nhiều công cụ cục bộ expose hợp đồng này. Ollama, LM Studio, máy chủ llama.cpp và vLLM đều cung cấp một endpoint kiểu OpenAI. Các dịch vụ lưu trữ cũng vậy, đó là lý do cùng hai mươi dòng mã client có thể giao tiếp với cả hai. Endpoint trên trang web này là một trong những loại được lưu trữ. Nó chấp nhận POST /v1/chat/completions và GET /v1/models, và nó được truy cập qua https://api.onekeyllmapi.com/v1.

Cục bộ so với lưu trữ

Không cái nào tốt hơn cái nào nói chung. Chúng đánh đổi sự kiểm soát lấy nỗ lực. Bảng chỉ nêu những khác biệt áp dụng cho danh mục, không phải cho bất kỳ sản phẩm cụ thể nào.

Nếu dữ liệu của bạn không bao giờ được rời khỏi một máy bạn kiểm soát, giải pháp cục bộ là lựa chọn tốt hơn và dịch vụ lưu trữ là công cụ không phù hợp. Nếu bạn cần một mô hình lớn hơn phần cứng của bạn hỗ trợ, hoặc một bot có thể truy cập được từ nhiều nơi, dịch vụ lưu trữ là lựa chọn tốt hơn. Một cấu hình phổ biến giữ cả hai và chọn theo nhiệm vụ.

Chuyển đổi client từ cục bộ sang lưu trữ

Nếu mã của bạn đã giao tiếp với trình chạy cục bộ, việc di chuyển chỉ liên quan đến ba giá trị. Mọi thứ khác, bao gồm cách bạn xây dựng thông báo và đọc các chunk truyền phát, vẫn giữ nguyên.

1. Base URL. Sử dụng https://api.onekeyllmapi.com/v1 thay vì địa chỉ cục bộ của bạn.
2. Khóa API. Các máy chủ cục bộ thường bỏ qua khóa. Một máy chủ lưu trữ yêu cầu nó dưới dạng Authorization: Bearer <key>, và SDK sẽ gửi nó cho bạn.
3. Model ID. Tên cục bộ là bất cứ thứ gì bạn đã kéo. Ở đây ID là uncensored.

Một cách gọn gàng để giữ cho điều này linh hoạt là đọc cả ba từ các biến môi trường, để một tệp hoạt động ở cả hai nơi.

Copyimport os
from openai import OpenAI

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

models = client.models.list()
print([m.id for m in models.data])

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "Answer in two sentences."},
        {"role": "user", "content": "Why do OpenAI-style endpoints make switching models easy?"},
    ],
    temperature=0.5,
)
print(resp.choices[0].message.content)

Gọi tương tự từ dòng lệnh, hữu ích cho một bài kiểm tra nhanh:

Copycurl https://api.onekeyllmapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "uncensored", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 20}'

Với Node, mẫu tương tự:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.LLM_BASE_URL ?? "https://api.onekeyllmapi.com/v1",
  apiKey: process.env.LLM_API_KEY,
});

const res = await client.chat.completions.create({
  model: process.env.LLM_MODEL ?? "uncensored",
  messages: [{ role: "user", content: "Name three uses for JSON mode." }],
});
console.log(res.choices[0].message.content);

Những gì tính tương thích OpenAI bao gồm và không bao gồm

Tương thích có nghĩa là định dạng dây khớp. Nó không đảm bảo rằng mọi tính năng mà dịch vụ gốc cung cấp đều có mặt. Trước khi di chuyển một ứng dụng thực, hãy kiểm tra từng mục trong số này với mục tiêu.

API này hỗ trợ

• Hoàn tất hội thoại tại POST /v1/chat/completions và danh sách mô hình tại GET /v1/models.
• Truyền phát qua các sự kiện do máy chủ gửi với stream: true, với việc sử dụng được báo cáo ở cuối luồng.
• Gọi công cụ thông qua tools và tool_choice, truyền phát tool_calls, và kết quả được gửi lại dưới dạng thông báo role: "tool".
• Chế độ JSON thông qua response_format: {"type": "json_object"}.
• Các điều khiển lấy mẫu: temperature, top_p, stop, seed và các tham số phạt được chuyển tiếp.

Nó không làm gì

• Không tạo hình ảnh, âm thanh hoặc video. Nó chỉ là văn bản.
• Không có endpoint embeddings và không có fine-tuning. Nếu ứng dụng của bạn xây dựng chỉ mục vector, bạn cần một nguồn embedding riêng biệt.
• Chỉ một mô hình. Mô hình là một mô hình trọng số mở do một nhà cung cấp độc lập chạy. Nó không phải là API chính thức của bất kỳ nhà cung cấp lớn nào, và nó không phải là bộ định tuyến giữa các nhà cung cấp, vì vậy bạn không thể chọn giữa các họ mô hình bằng cách thay đổi ID.

Các trình chạy cục bộ đôi khi khác theo chiều ngược lại: máy chủ cục bộ có thể cung cấp một tuyến nhúng hoặc cho phép bạn tải nhiều mô hình, và kích thước ngữ cảnh là bất cứ thứ gì bạn cấu hình. Hãy đọc tài liệu của từng mục tiêu và giữ một danh sách ngắn các tính năng mà ứng dụng của bạn thực sự sử dụng. Tài liệu quickstart hiển thị đầy đủ các trường yêu cầu.

Khác biệt về ngữ cảnh, giới hạn và chi phí

Ba con số thay đổi khi bạn rời khỏi máy chủ cục bộ. Cái đầu tiên là cửa sổ. Chiều dài ngữ cảnh của trình chạy cục bộ là một cài đặt gắn với bộ nhớ của bạn. Ở đây nó được cố định ở 100.000 token, dùng chung cho prompt và completion, và max_tokens là tùy chọn. Cái thứ hai là độ đồng thời. Máy của riêng bạn có thể bị xếp hàng sâu tùy thích, nhưng một khóa đầy đủ ở đây cho phép 8 yêu cầu đồng thời và 300 mỗi phút, và một khóa dùng thử là 2 và 60. Cái thứ ba là hóa đơn.

Chi phí sử dụng dịch vụ lưu trữ là $0,15 cho mỗi 1 triệu token đầu vào và $0,50 cho mỗi 1 triệu token đầu ra, trả theo từng lần sử dụng từ tín dụng trả trước. Hãy xem xét một công việc hàng ngày làm ví dụ: một bộ tóm tắt xử lý 400 tài liệu mỗi ngày, mỗi tài liệu 3.000 token đầu vào và 300 token đầu ra. Đầu vào là 400 x 3.000 = 1.200.000 token, chi phí 1,2 x $0,15 = $0,18. Đầu ra là 400 x 300 = 120.000 token, chi phí 0,12 x $0,50 = $0,06. Tổng cộng ngày là $0,24, và một tháng 30 ngày là $7,20. So sánh điều đó với chi phí duy trì GPU hoạt động và chi phí của thẻ trước khi bạn quyết định.

Khi bạn vượt quá giới hạn, API trả về HTTP 429 với mã rate_limited hoặc concurrency. Đối với tình trạng quá tải ngắn hạn, nó thêm Retry-After: 5. Hãy giữ logic thử lại chờ đợi và thử lại. Các yêu cầu bị lỗi hoặc bị từ chối không bị tính phí. Tín dụng không bao giờ hết hạn, vì vậy một tháng không hoạt động không tốn gì.

Một yêu cầu truyền phát giữ slot yêu cầu đồng thời của nó cho đến khi luồng kết thúc, vì vậy hãy đóng các luồng bạn ngừng đọc. Nạp tiền bắt đầu từ $20; các bậc và bonus có trên trang giá cả.

Gỡ lỗi khi việc chuyển đổi gặp sự cố

Hầu hết các lỗi migration đều do một vài nguyên nhân chính. Hãy khắc phục chúng theo thứ tự này.

• Lỗi 404 hoặc lỗi kết nối. Base URL có lẽ thiếu hậu tố /v1, hoặc có một đường dẫn bổ sung. Hãy sử dụng nó chính xác như https://api.onekeyllmapi.com/v1.
• Lỗi xác thực. Khóa bị thiếu hoặc được gửi trong header sai. Định dạng là Authorization: Bearer <key>. Người dùng SDK nên xác nhận biến môi trường thực sự đã được tải.
• Không tìm thấy mô hình. Tên mô hình cục bộ cũ vẫn còn trong cấu hình của bạn. Hãy gọi GET /v1/models và sử dụng ID mà nó liệt kê, đó là uncensored.
• Lỗi 429 khi tải cao. Bạn đang vượt quá 8 yêu cầu đồng thời hoặc 300 mỗi phút với khóa tiêu chuẩn. Hãy thêm hàng đợi hoặc semaphore.
• Một tham số dường như bị bỏ qua. Hãy kiểm tra xem đó có phải là một trong các trường được chuyển tiếp đã liệt kê ở trên không, và so sánh hành vi với seed cố định và nhiệt độ thấp.

Mọi phản hồi đều bao gồm header X-Request-Id. Hãy ghi lại nó bên cạnh ID yêu cầu của riêng bạn để một câu trả lời xấu có thể được truy vết sau này. Nếu bạn chạy lưu lượng sản xuất và muốn đo lường chất lượng theo thời gian, bài viết trên trang web Quan sát LLM: Những điều sai lầm và Sự thật là một tài liệu tham khảo tốt tiếp theo. Các header phản hồi X-Balance-USD, X-RateLimit-Limit-Requests và X-RateLimit-Limit-Concurrency cũng đáng để ghi lại.

Thử nó mà không cần cam kết

Cách rẻ nhất để kiểm tra xem mã của bạn có port sạch sẽ hay không là chạy nó một lần. Tạo tài khoản với Google hoặc email và mật khẩu, sau đó nhận tín dụng dùng thử $0,50 từ trang khóa. Nó chỉ mất một cú nhấp chuột, không cần thẻ, giới hạn một người dùng và có hiệu lực trong 7 ngày. Lấy khóa của bạn tại trang khóa API, đặt ba biến môi trường từ ở trên và chạy bộ kiểm tra hiện có của bạn.

Nếu các bài kiểm tra vượt qua và mức sử dụng phù hợp với ngân sách của bạn, hãy nạp tiền từ $20, bằng thẻ (Visa, Mastercard, Apple Pay, Google Pay) hoặc tiền mã hóa (USDT trên TRC20, USDC trên Base). Các prompt không được sử dụng để huấn luyện. Mô hình đượ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, với một quy tắc cố định: không có nội dung tình dục liên quan đến người chưa thành niên.

Hướng dẫn khác

• Quan sát LLM: Những điều sai lầm và sự thật