SDK API DeepSeek: Dùng SDK OpenAI và thay đổi endpoint

Tại sao SDK OpenAI là SDK API DeepSeek

Khi mọi người tìm kiếm một SDK API DeepSeek, họ mong đợi một gói phần mềm có tên của nhà cung cấp. Trên thực tế, tài liệu chính thức của DeepSeek mô tả việc gọi API của họ thông qua SDK OpenAI với base URL khác, vì API tuân theo định dạng yêu cầu và phản hồi của OpenAI. Hãy kiểm tra tài liệu hiện tại của họ để biết base URL chính xác và tên mô hình; họ là cơ quan có thẩm quyền về dịch vụ của mình.

Hệ quả là rất hữu ích. Bất kỳ mã nào được viết cho thư viện client OpenAI đều có thể giao tiếp với bất kỳ máy chủ nào triển khai các endpoint giống nhau, ở đây là POST /v1/chat/completions, POST /v1/responses và GET /v1/models. Việc chuyển đổi giữa các nhà cung cấp trở thành một thay đổi cấu hình thay vì viết lại mã. Phần còn lại của bài viết này trình bày mẫu mã trong Python, Node và curl, sau đó là một cấu trúc giúp việc chuyển đổi trở nên dễ dàng.

Thiết lập Python

Cài đặt gói chính thức và trỏ nó đến endpoint:

Copypip install openai

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.deepseekapi.top/v1",
    api_key="YOUR_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain idempotency in two sentences."},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

Lấy khóa trên trang khóa API. Người dùng mới có thể nhận $0,50 tín dụng dùng thử chỉ với một cú nhấp chuột, không cần thẻ. Bài viết DeepSeek API Python đi sâu hơn về ngôn ngữ này, bao gồm xử lý lỗi.

Thiết lập Node.js

Copynpm install openai

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseekapi.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "List four uses of a message queue." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Mẫu giống hệt nhau: base URL, khóa, model. Truyền phát (streaming) trả về Server-Sent Events, và thư viện chuyển đổi chúng thành một iterator không đồng bộ. Gọi hàm tuân theo cùng lược đồ với các API tương thích OpenAI khác: truyền tools, đọc tool_calls được truyền phát, và trả về kết quả dưới dạng các tin nhắn role: "tool".

Làm cho endpoint có thể thay đổi

Không cứng hóa ba giá trị. Đọc chúng từ môi trường và bao bọc việc tạo client trong một hàm. Sau đó, việc chuyển từ endpoint này sang endpoint khác chỉ nghĩa là chỉnh sửa tệp .env, không phải mã nguồn.

Copyimport os
from openai import OpenAI

def make_client():
    return OpenAI(
        base_url=os.environ.get("LLM_BASE_URL", "https://api.deepseekapi.top/v1"),
        api_key=os.environ["LLM_API_KEY"],
    )

MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt: str) -> str:
    r = make_client().chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,
    )
    return r.choices[0].message.content

Bây giờ, một nhà cung cấp khác chỉ cần ba biến môi trường. Các SDK chính thức cũng đọc OPENAI_API_BASE và OPENAI_API_KEY trong một số phiên bản, nhưng các biến rõ ràng giúp tránh những bất ngờ khi bạn sử dụng nhiều nhà cung cấp cùng lúc.

Nếu bạn dùng TypeScript hoặc ngôn ngữ khác, ý tưởng vẫn giống nhau: một hàm factory, ba biến, không có tên nhà cung cấp rải rác trong codebase. Một lỗi phổ biến là để tên nhà cung cấp rò rỉ vào tên hàm, thông báo log và tên biến, khiến việc chuyển đổi sau này khó hơn mức cần thiết. Hãy đặt tên theo công việc (ask, summarise) thay vì theo nhà cung cấp.

Giữ một bài kiểm tra nhỏ gửi một prompt cố định qua ask() và kiểm tra xem có câu trả lời không rỗng. Chạy nó sau mỗi lần thay đổi điểm cuối; nó phát hiện URL và khóa sai chỉ trong vài giây.

Những gì giữ nguyên và những gì thay đổi khi bạn chuyển đổi

Hàng cuối cùng là hàng thường khiến mọi người bất ngờ. Một endpoint tương thích ở mức giao thức, không phải ở mức hành vi. Hai nhà cung cấp có thể chấp nhận các yêu cầu giống hệt nhau và đưa ra câu trả lời rất khác nhau. Mô hình ở đây là một mô hình open-weight đơn lẻ từ một nhà cung cấp độc lập, được tinh chỉnh để trả lời mà không từ chối nội dung cho người dùng trưởng thành hợp pháp, và nó không phải là API chính thức của DeepSeek hoặc bất kỳ phòng thí nghiệm nào khác. Hãy kiểm tra lại các prompt mà bạn đã tinh chỉnh cho một mô hình khác.

Các tính năng endpoint này có và không có

• Hỗ trợ: chat completions, định dạng Responses, liệt kê mô hình, streaming, gọi hàm, chế độ JSON (response_format với json_object), và chuyển tiếp nhiệt độ, top_p, stop, seed và các khoản phạt.
• Không cung cấp: tạo hình ảnh, âm thanh hoặc video, embeddings, fine-tuning.
• Giới hạn: cửa sổ 100.000 token, kích thước body tối đa 8 MB, 8 yêu cầu đồng thời và 300 mỗi phút trên khóa đầy đủ (2 và 60 trên khóa dùng thử).
• Lỗi: HTTP 429 với mã rate_limited hoặc concurrency, và tiêu đề Retry-After: 5 khi quá tải tạm thời.

Nếu mã của bạn gọi một endpoint embeddings, bạn sẽ cần một nhà cung cấp khác cho phần đó và có thể giữ lại chat ở đây. Chia theo nhiệm vụ là lý do phổ biến cho mẫu biến môi trường ở trên.

Danh sách kiểm tra di chuyển

Khi bạn thay thế một endpoint bằng một endpoint khác trong một dự án hiện có, hãy làm theo một danh sách ngắn thay vì thay đổi mọi thứ cùng một lúc.

1. Chứng minh endpoint. Gửi một yêu cầu bằng curl và xác nhận bạn nhận được văn bản. Gọi GET /v1/models và kiểm tra xem id uncensored có được liệt kê không.
2. Thay đổi ba giá trị. Base URL, khóa, tên mô hình, không có gì khác. Không chạm vào prompt ngay.
3. Chạy các bài kiểm tra hiện có của bạn. Nếu bạn có các bài kiểm tra hồi quy prompt, hãy chạy chúng và ghi chú những bài nào thất bại. Các lỗi thường là về hành vi, chẳng hạn như định dạng đầu ra khác, không phải lỗi giao thức.
4. Kiểm tra các tham số. Loại bỏ các tùy chọn mà endpoint không cần. Giữ lại temperature, top_p, stop và seed nếu bạn sử dụng chúng.
5. Kiểm tra streaming và tools riêng biệt. Lỗi streaming thường ẩn trong mã client giả định một cấu trúc chunk cụ thể. Các lệnh gọi công cụ cần một schema mà mô hình tuân thủ tốt, vì vậy hãy kiểm tra với các hàm thực tế của bạn.
6. Đo lường chi phí và độ trễ trên lưu lượng thực. So sánh một ngày yêu cầu, không phải một prompt.

Hãy làm việc này trong một nhánh hoặc với một cờ tính năng định hướng một phần nhỏ lưu lượng đến endpoint mới. Vì mã client được chia sẻ, việc hoàn tác chỉ là thay đổi một biến môi trường.

Xử lý các lần thử lại và đọc mức sử dụng

Các SDK tự động thử lại một số lỗi theo mặc định, nhưng bạn vẫn nên tự xử lý lỗi 429, vì các giới hạn về độ đồng thời là có thật trong môi trường sản xuất. Hãy bắt ngoại lệ giới hạn tốc độ, chờ số giây trong Retry-After (5 khi quá tải), và thử lại vài lần. Các yêu cầu thất bại không bị tính phí, nên các lần thử lại an toàn cho số dư của bạn.

Ghi lại usage.prompt_tokens và usage.completion_tokens trên mọi lệnh gọi. Giá là $0.15 cho mỗi 1M token đầu vào và $0.50 cho mỗi 1M token đầu ra, vì vậy một lệnh gọi với 2.000 token đầu vào và 600 token đầu ra tốn 2.000 × $0.15 / 1M + 600 × $0.50 / 1M = $0.0003 + $0.0003 = $0.0006. Các tiêu đề phản hồi cũng bao gồm X-Balance-USD cho tín dụng còn lại. Xem trang giá để nạp tiền và nhận ưu đãi, và tài liệu để xem danh sách đầy đủ các tham số.

Trình soạn thảo và các công cụ khác

Ba giá trị này được chuyển sang bất kỳ công cụ nào có cài đặt nhà cung cấp tương thích OpenAI. Bài viết về cách sử dụng API kiểu DeepSeek trong Cursor sẽ hướng dẫn bạn qua một trình soạn thảo như vậy. Trong mỗi công cụ, các trường được đặt tên hơi khác nhau, nhưng bạn luôn nhập base URL kết thúc bằng /v1, khóa và tên mô hình.

Hướng dẫn khác

• Chi phí DeepSeek API so với OpenAI API: Ví dụ minh họa
• Khóa DeepSeek API: Truy cập LLM API không kiểm duyệt