API vs SDK: Chọn Cách Tích Hợp AI Nào Cho Dự Án?

Khi tích hợp AI vào dự án, bạn có hai lựa chọn: gọi trực tiếp API qua HTTP request, hoặc dùng SDK mà provider cung cấp. API linh hoạt, kiểm soát tối đa, không phụ thuộc package. SDK tiện lợi — tự động xử lý streaming, retry, error — nhưng tăng dependency. Chọn sai? Lãng phí thời gian debug hoặc tích lũy technical debt. Bài này phân tích rõ ưu nhược điểm từng cách, khi nào dùng gì, với ví dụ thực tế từ OpenAI, Anthropic, Google. Mục tiêu: giúp bạn quyết định đúng ngay từ đầu.

API là gì? SDK là gì?

API (Application Programming Interface) trong ngữ cảnh AI là các endpoint HTTP mà provider (OpenAI, Anthropic, Google…) cung cấp để bạn gửi request và nhận response. Bạn dùng bất kỳ HTTP client nào (fetch, axios, curl, HTTP client của ngôn ngữ) để gọi.

Ví dụ gọi OpenAI API bằng fetch:

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${OPENAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Xin chào' }]
  })
});
const data = await response.json();
console.log(data.choices[0].message.content);

SDK (Software Development Kit) là thư viện được provider hoặc cộng đồng xây dựng, đóng gói API thành các hàm/class tiện lợi, tự động xử lý authentication, retry, streaming, error parsing, type safety.

Cùng ví dụ trên với OpenAI SDK:

import OpenAI from 'openai';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const completion = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Xin chào' }]
});
console.log(completion.choices[0].message.content);

So sánh ưu nhược điểm

Tiêu chí	API (HTTP trực tiếp)	SDK
Linh hoạt	✅ Tuyệt đối — bạn kiểm soát toàn bộ request/response	⚠️ Phụ thuộc vào SDK có hỗ trợ feature mới không
Dependency	✅ Không cần cài package ngoài (chỉ cần HTTP client)	❌ Thêm 1+ package vào dự án (OpenAI SDK ~500KB)
Streaming	⚠️ Phải tự parse SSE (Server-Sent Events)	✅ Hỗ trợ sẵn .stream() hoặc async iterator
Error handling	⚠️ Tự check status code + parse error body	✅ Throw exception có type, message rõ ràng
Retry logic	❌ Phải tự implement (rate limit, timeout)	✅ Tự động retry với exponential backoff
Type safety	❌ Phải tự define TypeScript types	✅ Types đầy đủ (autocomplete, compile-time check)
Function calling	⚠️ Tự parse tool_calls + validate schema	✅ Helper parse + validate sẵn
Learning curve	⚠️ Phải đọc API docs chi tiết	✅ Docs + examples phong phú hơn
Ngôn ngữ niche	✅ Bất kỳ ngôn ngữ nào có HTTP client	❌ Chỉ hỗ trợ JS/Python/Go/Ruby… phổ biến

Khi nào dùng API trực tiếp?

1. Ngôn ngữ lập trình SDK không hỗ trợ

Bạn dùng Elixir / Zig / Haskell / ngôn ngữ ít phổ biến → SDK chính thức không có. Gọi API trực tiếp qua HTTP client là cách duy nhất.

2. Giảm dependency tối đa

Dự án microservice nhỏ, bạn không muốn thêm SDK ~500KB chỉ để gọi 1-2 endpoint đơn giản (vd: text embedding, moderation). Viết hàm fetch thuần 20 dòng đủ.

3. Kiểm soát tuyệt đối mọi chi tiết request

Bạn cần custom header, timeout chính xác, proxy đặc biệt, hoặc log toàn bộ raw request/response để audit → API trực tiếp cho phép can thiệp mọi bước.

4. Dùng provider mới / beta feature chưa có trong SDK

OpenAI vừa ra API mới (vd: Batch API, Realtime API beta) nhưng SDK chưa update → bạn phải gọi trực tiếp theo docs.

Khi nào dùng SDK?

1. Streaming realtime (chat AI)

Streaming response từ LLM (từng token trả về dần) yêu cầu parse SSE (Server-Sent Events). SDK đã làm sẵn:

const stream = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Kể câu chuyện dài' }],
  stream: true
});

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

Tự implement SSE parser bằng fetch thuần phức tạp (phải xử lý chunked transfer, backpressure, reconnect).

2. Function calling / Tool use

OpenAI function calling, Anthropic tool use, Google function declarations → SDK tự parse tool_calls, validate schema, helper gọi hàm:

const completion = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Thời tiết Hà Nội hôm nay?' }],
  tools: [{ type: 'function', function: { name: 'get_weather', parameters: {...} } }]
});

const toolCall = completion.choices[0].message.tool_calls[0];
// SDK đã parse sẵn toolCall.function.name, toolCall.function.arguments

3. Retry tự động cho rate limit / timeout

Provider có rate limit (vd: OpenAI tier free 3 req/min). SDK tự retry với exponential backoff khi gặp 429 Too Many Requests. Tự làm tốn thời gian.

4. Type safety + autocomplete (TypeScript)

SDK official có types đầy đủ → VSCode autocomplete tên field, catch lỗi compile-time, refactor an toàn.

5. Dự án production cần ổn định

SDK được test kỹ với edge case: network không ổn, response lỗi định dạng, vượt token limit. Tự viết lại từ đầu? Lãng phí thời gian.

So sánh SDK của các provider lớn

OpenAI SDK (openai)

• Ngôn ngữ: Python, Node.js, Go (chính thức)
• Điểm mạnh: Streaming đầy đủ, function calling helper, vision/audio support, batch API
• Khi nào dùng: Dự án cần GPT-4/o1/Whisper/DALL-E, production-grade

Anthropic SDK (@anthropic-ai/sdk)

• Ngôn ngữ: Python, TypeScript
• Điểm mạnh: Streaming tốt, prompt caching (giảm cost lớn cho context dài), tool use (tương tự function calling)
• Khi nào dùng: Dùng Claude Opus/Sonnet, cần context dài (200K tokens), realtime chat

Google Generative AI SDK (@google/generative-ai)

• Ngôn ngữ: Python, Node.js, Go, Kotlin, Swift
• Điểm mạnh: Multimodal đơn giản (text + image + video + audio cùng lúc), function declarations
• Khi nào dùng: Dùng Gemini 1.5 Pro/Flash, cần xử lý ảnh/video trong prompt

LangChain / LlamaIndex (wrapper SDK)

• Điểm mạnh: Abstraction cao cho RAG (Retrieval-Augmented Generation), agent, multi-step workflow
• Nhược điểm: Thêm 1 lớp abstraction → đôi khi chậm update feature mới, khó debug khi lỗi
• Khi nào dùng: Xây RAG pipeline phức tạp, cần chain nhiều bước (retrieve → rerank → generate)

Ví dụ thực tế: Chọn API hay SDK?

Case 1: Chatbot đơn giản (1-2 turn)

Yêu cầu: User hỏi → AI trả lời 1 lần, không streaming, không function calling.

Chọn: API trực tiếp (fetch 20 dòng code, không cần SDK).

Case 2: Chat realtime với streaming

Yêu cầu: UI hiển thị từng chữ AI trả lời (như ChatGPT).

Chọn: SDK (streaming SSE phức tạp, SDK làm sẵn).

Case 3: AI agent gọi tool (search web, query DB)

Yêu cầu: AI quyết định gọi hàm nào, bạn execute rồi trả kết quả lại.

Chọn: SDK (function calling helper tiết kiệm thời gian).

Case 4: Batch xử lý 10,000 văn bản

Yêu cầu: Gửi batch requests, xử lý async, retry khi fail.

Chọn: SDK nếu có (OpenAI Batch API SDK), hoặc API trực tiếp + tự quản lý queue.

Case 5: Ngôn ngữ Rust / Elixir

Yêu cầu: Dự án backend Rust, SDK chính thức không có.

Chọn: API trực tiếp (reqwest crate cho Rust).

Hybrid: Dùng cả hai

Một số dự án dùng SDK cho core features (chat, streaming) + API trực tiếp cho edge case (beta feature, custom header). Ví dụ:

• SDK OpenAI cho chat completion
• API trực tiếp cho Batch API (SDK chưa hỗ trợ đủ)
• API trực tiếp cho moderation endpoint (đơn giản, không cần SDK)

Lời khuyên chọn lựa

1. Dự án production, ngôn ngữ phổ biến (JS/Python) → Dùng SDK chính thức (OpenAI, Anthropic, Google).
2. Dự án nhỏ, 1-2 API call đơn giản → API trực tiếp (fetch/axios).
3. Cần streaming hoặc function calling → SDK (tránh reinvent SSE parser).
4. Ngôn ngữ niche → API trực tiếp (không có lựa chọn khác).
5. Wrapper SDK (LangChain/LlamaIndex) → Chỉ dùng khi xây RAG/agent phức tạp; tránh nếu use case đơn giản (overhead không đáng).

Tổng kết

API và SDK phục vụ trường hợp khác nhau. API trực tiếp cho kiểm soát và linh hoạt; SDK cho tiện lợi và ổn định.

Hiểu rõ yêu cầu dự án (streaming? function calling? retry?) → chọn đúng công cụ ngay từ đầu. Tránh refactor sau.

Với hầu hết dự án production dùng AI, SDK chính thức từ provider là lựa chọn an toàn nhất.

Đọc thêm:

• RAG Là Gì? Cách Doanh Nghiệp Dùng AI Trả Lời Từ Dữ Liệu Riêng — Khi nào cần RAG và tool nào (LangChain vs tự build).
• LangChain Vs LlamaIndex: So Sánh Thực Tế Cho Dự Án AI — Wrapper SDK nào phù hợp với pipeline AI của bạn.
• Local LLM: Chạy AI Riêng Tư Trên Máy Cá Nhân — Alternative khi không muốn phụ thuộc cloud API.