Hướng dẫn tích hợp DeepSeek API qua ECAIX với OpenAI SDK

Bài viết này hướng dẫn cách kiểm tra một model ID DeepSeek thông qua endpoint tương thích OpenAI của ECAIX. Bạn sẽ thấy cách gửi request tối thiểu, cấu hình Python và curl, kiểm tra model ID, streaming, JSON, tools và chẩn đoán các lỗi phổ biến.

Bài viết mô tả cách truy cập gateway ECAIX tới một model ID đang xuất hiện trong catalog ECAIX. Đây không phải là tuyên bố rằng ECAIX là endpoint DeepSeek chính thức, cũng không có nghĩa mọi tính năng DeepSeek đều hoạt động trên mọi route của gateway. Hãy kiểm tra model page trực tiếp và tài liệu của provider trước khi đưa workload vào production.

Bắt đầu nhanh

Nếu ứng dụng của bạn đã dùng OpenAI SDK, hãy đi theo trình tự sau:

1. Mở trang model DeepSeek v4.1 Flash và xác nhận model ID còn khả dụng.
2. Tạo ECAIX API key.
3. Đặt base URL OpenAI-compatible là https://ecaix.com/api/ai/v1.
4. Giữ nguyên SDK và code ứng dụng nếu có thể.
5. Chạy request tối thiểu bên dưới.
6. Chỉ thêm streaming, JSON hoặc tools sau khi request cơ bản thành công.

Endpoint và model ID

Với client tương thích OpenAI, sử dụng:

Base URL: https://ecaix.com/api/ai/v1
Model:    deepseek-v4.1-flash

Model ID trong bài viết không phải một cam kết vĩnh viễn. Hãy xác nhận lại trong model directory trực tiếp trước mỗi lần tích hợp hoặc triển khai. Nếu cần một thành viên khác trong DeepSeek family, hãy sao chép đúng ID từ model detail page thay vì tự đoán hậu tố.

Endpoint cũng rất quan trọng. SDK nên nhận base path kết thúc ở /v1; SDK sẽ tự thêm /chat/completions hoặc operation path tương ứng. Không thêm /chat/completions vào base_url nếu SDK đã tự thêm path đó.

Python với OpenAI SDK

Cài hoặc nâng cấp OpenAI Python SDK trong virtual environment:

python -m pip install --upgrade openai

Ví dụ:

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

const response = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [
    { role: "user", content: "Return one short sentence about API testing." },
  ],
  max_tokens: 128,
});

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

Hãy chạy request ở server-side. Ứng dụng trên browser nên gọi backend của bạn thay vì để lộ ECAIX key trong JavaScript phía client.

Request curl để chẩn đoán

Khi SDK gặp lỗi, hãy loại SDK khỏi phương trình và kiểm tra endpoint trực tiếp. Lưu header và body riêng để phân biệt lỗi HTTP với lỗi response format.

curl -sS -D /tmp/ecaix-deepseek-headers.txt \
  -o /tmp/ecaix-deepseek-response.json \
  -w '\nHTTP %{http_code}\n' \
  "https://ecaix.com/api/ai/v1/chat/completions" \
  -H "Authorization: Bearer ${ECAIX_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ],
    "max_tokens": 128
  }'

Không dán header hoặc response đã lưu vào issue công khai nếu chưa xóa API key, request ID, prompt, đường dẫn repository và dữ liệu khách hàng.

Quy trình chẩn đoán response

Hãy kiểm tra theo thứ tự:

1. HTTP status: request có tới endpoint hợp lệ hay không.
2. Response body: đọc error code của gateway hoặc provider.
3. Model ID: sao chép đúng ID từ model directory hiện tại.
4. Authentication: kiểm tra header key, account và quyền.
5. Request shape: giảm body về model, messages và output limit nhỏ.
6. Feature fields: thêm streaming, JSON hoặc tools từng bước.
7. SDK behavior: so sánh request của SDK với request curl trực tiếp.

Quy trình này giúp phân biệt lỗi thư viện client với lỗi routing model hoặc quyền tài khoản.

Streaming response

Chỉ thêm streaming sau khi request bình thường đã thành công:

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Summarize API retries in three points."}],
    stream=True,
    max_tokens=256,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Event behavior phụ thuộc endpoint và SDK. Hãy kiểm tra empty delta, final usage event, connection interruption và cách kết thúc stream. Không coi streaming là production-ready trước khi test disconnect và retry.

Structured output và JSON

Nếu cần output máy đọc được, hãy bắt đầu bằng request bình thường rồi mới thêm option structured output được endpoint và model hỗ trợ. Luôn parse kết quả bằng JSON parser thật. Prompt “hãy trả về JSON” không giống schema-enforced response.

import json

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {"role": "user", "content": "Return a JSON object with keys title and priority."}
    ],
    response_format={"type": "json_object"},
    max_tokens=128,
)

payload = json.loads(response.choices[0].message.content)
print(payload["title"])

response_format có được chấp nhận hay không phụ thuộc model và route. Nếu nhận lỗi unsupported parameter, hãy bỏ field đó và kiểm tra tài liệu của route trước khi thử format khác.

Function calling và tools

Tool calling cần được test riêng với text generation. Bắt đầu bằng một function an toàn, kiểm tra name và arguments trước khi thực thi.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_demo_status",
            "description": "Return a fixed status for a local compatibility test.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False,
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Check the demo status."}],
    tools=tools,
    tool_choice="auto",
    max_tokens=128,
)

print(response.choices[0].message.tool_calls)

Model có thể trả lời text bình thường nhưng tool calling thất bại vì schema conversion, parameter không hỗ trợ hoặc behavior riêng của client. Không thực thi arguments trên hệ thống production trước khi validate schema và thêm authorization checks.

OpenAI-compatible và Anthropic-compatible

ECAIX có các compatibility surface khác nhau cho từng loại client:

Đọc Chat Completions docs, Responses docs và Anthropic Messages docs trước khi chọn path. Cùng một model ID có thể không cung cấp cùng field hoặc behavior trên mọi compatibility surface.

Model detail pages hiện tại

Dùng model detail pages để kiểm tra capability và availability:

• DeepSeek v4.1 Flash
• DeepSeek v4 Pro 202606
• Qwen 3.8 Flash
• GLM 5.3

Các trang này đáng tin cậy hơn bài blog tĩnh để kiểm tra model ID, context và link giá hiện tại.

Lỗi thường gặp

Checklist an toàn trước production

Trước khi rời khỏi test project, hãy xác nhận:

• API key nằm ở server và có thể rotate.
• Prompt và response không chứa secret hoặc dữ liệu khách hàng chưa được phép.
• Bạn hiểu gateway log request thế nào và lưu trong bao lâu.
• Model availability và giá được kiểm tra ở live pages.
• Ứng dụng xử lý timeout, retry, idempotency và rate limit.
• Streaming disconnect không tạo duplicate job.
• Tool calls có allowlist, validation, authorization và audit log.
• Điều khoản của provider và gateway cho phép workload bạn gửi.

Ghi lại kiểm tra trước khi phát hành

Hãy ghi ngày kiểm tra, phiên bản client, model ID, endpoint, HTTP status và các feature đã thực sự chạy. Nếu chưa kiểm tra, hãy đánh dấu là chưa xác minh. Bản ghi này giúp so sánh sau khi model hoặc gateway thay đổi, đồng thời tránh biến một ví dụ blog cũ thành giả định production không có căn cứ.

FAQ

Đây có phải DeepSeek API endpoint chính thức không?

Không. Bài viết mô tả truy cập gateway ECAIX tới model ID xuất hiện trong ECAIX catalog. Dùng DeepSeek API documentation chính thức cho endpoint native, account rules và capability riêng của provider.

Có thể dùng OpenAI SDK mà không viết lại ứng dụng không?

Nhiều ứng dụng OpenAI SDK có thể bắt đầu bằng cách đổi base URL, API key và model ID. Tuy nhiên vẫn cần test field support, streaming, tools, response format và error handling.

Nên chọn DeepSeek model nào?

Bắt đầu từ model directory và chọn theo coding, reasoning, context length, multimodal hoặc yêu cầu chi phí. Không chọn chỉ dựa trên model name trong bài viết cũ. Hãy xác nhận ID hiện tại và test bằng prompt của chính bạn.

Có thể dùng với Claude Code không?

Anthropic-compatible path có thể được test như một third-party provider workflow, nhưng Anthropic không hỗ trợ route Claude Code tới non-Claude models qua gateway. Không mô tả đây là Anthropic official support hoặc full Claude Code compatibility.

Xem giá và giới hạn ở đâu?

Dùng ECAIX pricing, model directory và account controls. Không hard-code giá từ bài viết vào ứng dụng.

Bước tiếp theo

1. Xác nhận model ID trong DeepSeek model page hiện tại.
2. Tạo ECAIX API key.
3. Đọc Chat Completions docs.
4. Chạy curl diagnostic trực tiếp.
5. Chỉ chuyển sang SDK sau khi request trực tiếp thành công.
6. Thêm streaming, JSON hoặc tools từng feature một.

Nguồn

• DeepSeek API documentation
• ECAIX Chat Completions documentation
• ECAIX Responses documentation
• ECAIX Anthropic Messages documentation