Bản thân việc tích hợp DeepSeek API không phức tạp; điều thực sự dễ làm người ta mắc kẹt là ba việc: khóa thuộc nền tảng nào, Base URL đã ghi đầy đủ chưa, tên mô hình có phải phiên bản hiện tại không. Nhiều trường hợp “gọi không được” không phải do năng lực mô hình mà do thông tin xác thực và địa chỉ chưa khớp nhau.
Bài viết bắt đầu từ đăng ký, nạp tiền, tạo khóa, lần lượt hoàn thành lần gọi curl và Python đầu tiên, sau đó nói rõ truyền phát, chế độ thinking, max_tokens và các lỗi thường gặp. Làm theo một lượt về cơ bản có thể chạy thông toàn bộ chuỗi tích hợp.
Lưu ý: DeepSeek là nhãn hiệu của chủ sở hữu tương ứng; bài viết không có quan hệ trực thuộc với DeepSeek chính thức. Tên mô hình, tham số và giới hạn có thể điều chỉnh theo phiên bản; bài lấy hình thức phổ biến trong tài liệu chính thức tháng 10 năm 2026 làm ví dụ, cuối cùng căn cứ tài liệu chính thức và bảng giá mô hình trên site.
1. Phân biệt bốn thứ trước khi tích hợp
Tích hợp API thất bại phần lớn không phải vấn đề năng lực mô hình, mà do bốn đối tượng dưới đây chưa khớp:
| Đối tượng | Vai trò | Chỗ dễ sai nhất |
|---|---|---|
| Tài khoản | Quyết định số dư, hóa đơn và quyền sở hữu khóa | Lấy khóa nền tảng A cấu hình địa chỉ nền tảng B |
| API Key | Thông tin xác thực | Khi sao chép dính khoảng trắng, xuống dòng hoặc dấu ngoặc |
| Base URL | Yêu cầu gửi tới điểm vào nào | Thiếu /v1, hoặc trộn địa chỉ chính thức với địa chỉ cổng |
| Tên mô hình | Trường model trong yêu cầu |
Dùng tên đã hết hiệu lực trong bài cũ |
Cách nhớ rất đơn giản: khóa và Base URL phải đi thành cặp. Khóa chính thức chỉ đi với điểm vào chính thức, khóa cổng chỉ đi với điểm vào cổng; trộn lẫn thường trả về 401 ngay.
2. Đăng ký, nạp tiền, tạo khóa
Lấy nền tảng mở chính thức làm ví dụ, thứ tự như sau:
- Mở nền tảng mở DeepSeek, đăng ký và đăng nhập.
- Làm theo hướng dẫn trên trang để hoàn tất xác minh cần thiết, vào trang nạp tiền.
- Lần đầu nạp số tiền nhỏ, xác nhận đã vào tài khoản rồi mới chạy nhiệm vụ hàng loạt.
- Vào trang API Keys, tạo khóa mới, đặt tên rõ mục đích, ví dụ
deepseek-test,deepseek-prod. - Sao chép khóa và lưu ngay vào trình quản lý mật khẩu hoặc biến môi trường phía máy chủ; sau khi đóng trang thường không hiển thị đầy đủ nữa.
- Tạo khóa riêng cho kiểm thử và sản xuất, đặt ngân sách hoặc nhắc nhở mức dùng.
Nếu dùng ZSQH AI Gateway, quy trình tương tự: tạo tài khoản tại trang đăng ký, vào bảng điều khiển tạo khóa, nạp tiền, rồi gọi theo cách tương thích OpenAI ở phần sau. Hai bên không nên dùng chung một khóa, nếu không khi có sự cố rất khó phân biệt là số dư, giới hạn tốc độ hay cấu hình sai.
3. Base URL và tên mô hình: xác nhận trước khi viết mã
Tài liệu chính thức hiện đưa ra điểm vào tương thích OpenAI là https://api.deepseek.com, đường dẫn chat completions là /chat/completions. Một số hướng dẫn cũ ghi https://api.deepseek.com/v1; có dùng được hay không phải căn cứ mô tả hiện tại của tài liệu chính thức; khi không chắc, hãy chạy thông bằng địa chỉ trong ví dụ chính thức trước.
| Hạng mục | Kết nối chính thức | ZSQH AI Gateway |
|---|---|---|
| Base URL | https://api.deepseek.com |
https://ai.zhongshangqihang.com/v1 |
| Đường dẫn chat | /chat/completions |
/v1/chat/completions |
| Nguồn khóa | Nền tảng mở chính thức | Bảng điều khiển cổng |
| Tên mô hình | Theo tài liệu chính thức | Theo bảng giá mô hình trên site |
| Phù hợp | Chỉ dùng DeepSeek, truy cập và thanh toán chính thức thuận lợi | Cần đầu mối thống nhất, nhiều mô hình hoặc hóa đơn nhân dân tệ |
Tính đến tháng 10 năm 2026, tên mô hình được tài liệu chính thức liệt kê là deepseek-flash và deepseek-v4-pro; các tên deepseek-chat, deepseek-reasoner trong bài cũ không chắc còn khả dụng. Đừng điền tên mô hình theo trí nhớ; hãy đối chiếu tài liệu chính thức hoặc trang giá trên site trước khi gọi.
4. Lần gọi curl đầu tiên: chạy thông yêu cầu tối thiểu
Trước hết tắt thinking để giảm biến số. Ví dụ với điểm vào chính thức:
export DEEPSEEK_API_KEY="sk-khoa-cua-ban"
curl "https://api.deepseek.com/chat/completions" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"messages": [{"role": "user", "content": "Chỉ trả lời OK"}],
"thinking": {"type": "disabled"},
"max_tokens": 32
}'
Trả về 200 và choices[0].message.content có nội dung nghĩa là khóa, Base URL và tên mô hình đều đúng. Nếu dùng cổng, chỉ thay URL thành https://ai.zhongshangqihang.com/v1/chat/completions và đổi sang khóa cổng.
Lưu ý thinking là tham số mở rộng của DeepSeek, không phải dịch vụ tương thích OpenAI nào cũng hỗ trợ. Nếu cổng không hỗ trợ, hãy bỏ trường này hoặc đổi sang tham số tương ứng theo tài liệu cổng.
5. Lần gọi Python đầu tiên: dùng SDK OpenAI
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com", # Với cổng đổi thành https://ai.zhongshangqihang.com/v1
)
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "Bạn là trợ lý kỹ thuật tiếng Việt, trả lời ngắn gọn."},
{"role": "user", "content": "Giải thích cơ sở dữ liệu vector là gì trong ba câu."},
],
max_tokens=512,
extra_body={"thinking": {"type": "disabled"}},
)
print(resp.choices[0].message.content)
print(resp.usage)
SDK OpenAI không nhận trường thinking, nên phải truyền qua extra_body. Sau khi chạy thông, hãy xem usage: đầu vào và đầu ra bao nhiêu Token, bộ nhớ đệm có trả về hay không, nội dung suy luận có được tính riêng không. Những dữ liệu này hữu ích hơn cảm giác “nhanh hay chậm” cho việc đặt chi phí và thời gian chờ về sau.
6. Truyền phát và reasoning_content
Thinking mặc định bật, cường độ mặc định là high. Khi bật, phản hồi sẽ có reasoning_content, ngang cấp với nội dung cuối cùng content; trong phản hồi truyền phát, nó được trả từng khối trong delta.reasoning_content.
stream = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "Viết một ví dụ Python đọc tệp CSV"}],
stream=True,
max_tokens=4096,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
reasoning, answer = [], []
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None):
reasoning.append(delta.reasoning_content)
if delta.content:
answer.append(delta.content)
print("Quá trình suy nghĩ:", "".join(reasoning))
print("Câu trả lời cuối cùng:", "".join(answer))
Trong hội thoại nhiều lượt, nếu yêu cầu có tools, reasoning_content của lượt trước phải được gửi lại đầy đủ, nếu không có thể trả về 400; khi không có tools thì có thể bỏ qua, máy chủ sẽ bỏ qua trường này. Với người dùng cuối, nên thu gọn nội dung suy nghĩ, không mặc định mở hết.
7. Cấu hình max_tokens, temperature và thinking
| Nhiệm vụ | thinking | Điểm bắt đầu đề xuất | Ghi chú |
|---|---|---|---|
| Kiểm tra kết nối | Tắt | max_tokens 32–128 | Chỉ cần một câu trả lời ngắn |
| Phân loại, trích xuất | Tắt | 256–1024 | Đầu ra có cấu trúc, giảm chi phí suy nghĩ |
| Chăm sóc khách hàng, viết | Bật | 1024–4096 | Có thể điều chỉnh effort theo kết quả |
| Mã, suy luận phức tạp | Bật | Từ 4096 trở lên | Để đủ ngân sách cho quá trình suy nghĩ |
Tài liệu chính thức hiện ghi: độ dài ngữ cảnh 1M Token, phạm vi max_tokens từ 1 đến 384K; khi không đặt, chế độ không thinking mặc định 8K, thinking mặc định 64K, khi reasoning_effort là max mặc định 128K. Các con số này có thể điều chỉnh, căn cứ tài liệu chính thức.
Trong chế độ thinking, temperature, presence_penalty, frequency_penalty không có hiệu lực; chỉnh chúng không báo lỗi nhưng cũng không thay đổi kết quả. max_tokens cũng không nên đặt quá thấp: nội dung suy nghĩ chiếm ngân sách đầu ra, ngân sách quá nhỏ có thể bị cắt trước khi viết tới nội dung chính.
8. Xử lý 401, 402, 429 và quá thời gian
| Hiện tượng | Nguyên nhân thường gặp | Xử lý |
|---|---|---|
| 401 | Sai khóa, thiếu Bearer, khóa và Base URL không cùng nền tảng | Sao chép lại khóa, kiểm tra header, xác nhận điểm vào khớp |
| 402 | Số dư tài khoản không đủ | Nạp tiền rồi thử lại; kiểm tra số dư trước khi sửa mã |
| 429 | Yêu cầu quá nhanh, vượt mức đồng thời hoặc QPS | Giảm đồng thời, lùi hàm mũ, tách khóa theo dự án |
| 400/422 | Tham số, tên mô hình hoặc ngữ cảnh không hợp lệ | Xem thông báo lỗi, đối chiếu tên mô hình và max_tokens |
| Quá thời gian | Mạng, đầu ra dài, thinking tốn thời gian | Đặt riêng thời gian chờ kết nối và đọc, giới hạn đầu ra |
| 500/503 | Dịch vụ thượng nguồn lỗi hoặc quá tải | Chờ ngắn rồi thử lại có lùi |
Giới hạn đồng thời của 429 được tính theo tài khoản, không chia đều cho từng khóa. Nhiều khóa trong cùng tài khoản dùng chung hạn mức, nên “tạo thêm vài khóa” không thể lách giới hạn đồng thời. Tài liệu chính thức còn nêu: nếu trong 10 phút chưa bắt đầu suy luận, kết nối sẽ bị ngắt; phía client cần nhận biết trường hợp này và thử lại.
9. An toàn khóa: tối thiểu năm việc trước khi lên tuyến
- Khóa chỉ đặt trong biến môi trường phía máy chủ hoặc dịch vụ quản lý khóa, không ghi vào frontend, kho mã và nhật ký.
- Kiểm thử, tiền sản xuất và sản xuất mỗi môi trường một khóa để nhanh chóng xác định và vô hiệu hóa khi sự cố.
- Đặt nhắc số dư hoặc giới hạn chi tiêu để cắt lỗ khi có gọi bất thường.
- Nhật ký chỉ ghi tiền tố hoặc dấu vân tay của khóa, không ghi giá trị đầy đủ.
- Khi nhân sự thay đổi hoặc nghi ngờ rò rỉ, luân chuyển ngay và kiểm tra nhật ký mức dùng gần đây.
10. Chuyển từ chính thức sang cổng: chỉ đổi hai chỗ
Khi di chuyển, trước hết đổi base_url và api_key, xác nhận lại tên mô hình theo trang giá của cổng, giữ nguyên thân yêu cầu nhiều nhất có thể. Dùng cùng một bộ lời nhắc thật để so sánh đầu ra, thời gian và usage, quan sát 3–7 ngày rồi mới chuyển sản xuất. Giữ kết nối chính thức làm kênh dự phòng để có thể quay lui nhanh.
Nếu cần đầu mối thống nhất hoặc hóa đơn đa mô hình, có thể tạo khóa thử nghiệm tại ZSQH AI Gateway; giá và mô hình khả dụng xem tại bảng giá mô hình.
Đọc thêm:
- Bảng giá và cách tính phí DeepSeek API
- DeepSeek API qua trung chuyển: giá, độ ổn định và di chuyển
- Xem bảng giá mô hình và cách tính chi phí
Câu hỏi thường gặp
Base URL có cần thêm /v1 không?
Căn cứ ví dụ hiện tại của tài liệu chính thức. Điểm vào tương thích OpenAI chính thức được ghi là https://api.deepseek.com, đường dẫn chat là /chat/completions; cổng thường dùng tiền tố /v1. Đừng đoán theo hướng dẫn cũ; trước hết dùng curl gọi thử địa chỉ đầy đủ.
401 là sai khóa hay không đủ số dư?
401 là lỗi xác thực; ưu tiên kiểm tra khóa đúng không, có mang Bearer không, khóa và Base URL có cùng nền tảng không. Không đủ số dư thường trả về 402; đừng nhầm hai loại.
Lần gọi đầu có nên bật thinking?
Nên tắt trước, dùng yêu cầu ngắn nhất để xác nhận đường truyền. Sau khi xác nhận khóa, địa chỉ, tên mô hình đều đúng, mới bật theo nhu cầu nhiệm vụ và bắt đầu thử từ reasoning_effort thấp.
max_tokens đặt bao nhiêu là hợp lý?
Trước hết đặt một giá trị đủ dùng theo nhiệm vụ, chạy thông rồi mới siết lại. Phân loại và trích xuất có thể bắt đầu từ vài trăm; văn bản dài và mã để vài nghìn; chế độ thinking cần chừa ngân sách cho nội dung suy nghĩ, đặt quá nhỏ dễ cắt mất phần chính.
Khóa chính thức có cấu hình trực tiếp với địa chỉ cổng được không?
Không. Khóa chính thức chỉ tương ứng điểm vào chính thức, khóa cổng chỉ tương ứng điểm vào cổng; trộn lẫn thường trả về 401. Khi đổi điểm vào, khóa và Base URL phải đổi thành cặp.
