Vấn Đề Mà Hầu Hết Các Tutorial Không Đề Cập
Bạn đã nghe về Gemini và muốn thử, nhưng rồi lại bị chặn ngay từ đầu: tài liệu chính thức giả định bạn đã biết nên chọn model nào, cài SDK nào, và multimodal input hoạt động ra sao. Kết quả là 15 tab trình duyệt mở toang mà vẫn không có dòng code nào chạy được.
Tôi cũng từng trải qua điều đó khi lần đầu tích hợp Gemini vào một dự án cá nhân. Điều thực sự giúp ích là nắm vững ba khái niệm cốt lõi trước. Sau đó mới viết code thực sự chạy được — không phải copy-paste ví dụ mà lỗi âm thầm không báo.
Hướng dẫn này bao gồm chính xác điều đó. Sau khi đọc xong, bạn sẽ có một script Python hoạt động được gọi Gemini, hiểu khi nào dùng model nào, và biết cách xử lý text, ảnh, cùng streamed response.
Các Khái Niệm Cốt Lõi Cần Nắm Trước
1. Dòng Sản Phẩm Gemini Model
Google cung cấp nhiều model Gemini, mỗi loại có sự đánh đổi khác nhau giữa chi phí và khả năng:
- Gemini 2.0 Flash — Nhanh, rẻ, lý tưởng cho môi trường production khi cần tốc độ ở quy mô lớn.
- Gemini 1.5 Pro — Context window lớn hơn (lên đến 1M token), suy luận tốt hơn, chi phí cao hơn. Dùng cho tài liệu dài hoặc phân tích phức tạp.
- Gemini 1.5 Flash — Cân bằng giữa Flash và Pro. Lựa chọn tốt cho hầu hết các trường hợp sử dụng.
Với 90% dự án của lập trình viên mới, hãy bắt đầu với gemini-2.0-flash. Nó nhanh và gói miễn phí đủ rộng rãi để làm prototype mà không tốn đồng nào.
2. Multimodal Input
Hầu hết các API chỉ nhận text. Gemini xử lý tự nhiên text, ảnh, audio, video và tài liệu — tất cả trong cùng một request. Không cần endpoint vision riêng, không cần SDK bổ sung. Bạn chỉ cần truyền byte ảnh cùng với text prompt của mình.
3. Hai Cách Tiếp Cận SDK
Có hai thư viện Python cho Gemini:
- google-genai — SDK mới hơn, được khuyến nghị. API gọn hơn, hỗ trợ streaming, async và tất cả model hiện tại.
- google-generativeai — SDK cũ hơn. Vẫn hoạt động nhưng đang dần bị loại bỏ khỏi các tính năng mới.
Dùng google-genai cho mọi dự án mới. Đó cũng là SDK được dùng trong hướng dẫn này.
Thực Hành
Bước 1: Lấy API Key
Truy cập Google AI Studio, đăng nhập bằng tài khoản Google và nhấn Get API Key. Sao chép key — bạn sẽ cần dùng ngay sau đây.
Gói miễn phí cho phép 15 request mỗi phút và 1 triệu token mỗi ngày với model Flash. Hơn đủ để xây dựng và kiểm thử một dự án thực tế.
Bước 2: Cài Đặt SDK
pip install google-genaiHoặc nếu bạn đang dùng virtual environment (khuyến nghị):
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install google-genaiBước 3: Gọi API Lần Đầu
Tạo file gemini_test.py và thêm đoạn code sau:
import os
from google import genai
# Thực hành tốt: lưu key trong biến môi trường
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
response = client.models.generate_content(
model="gemini-2.0-flash",
contents="Giải thích REST API là gì trong 3 câu, cho người mới bắt đầu học lập trình."
)
print(response.text)Chạy lên:
export GEMINI_API_KEY="api-key-của-bạn"
python gemini_test.pyBạn sẽ nhận được câu giải thích ngắn gọn, rõ ràng trong vòng 1-2 giây.
Bước 4: Streaming Response
Với các output dài, streaming giúp người dùng thấy phản hồi ngay lập tức thay vì chờ toàn bộ response. Điều này rất quan trọng trong các giao diện chat.
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
for chunk in client.models.generate_content_stream(
model="gemini-2.0-flash",
contents="Viết một hàm Python để parse file CSV và trả về danh sách các dict."
):
print(chunk.text, end="", flush=True)
print() # xuống dòng ở cuốiMỗi chunk.text đến khi Gemini tạo ra nó. Người dùng thấy output xuất hiện trong chưa đến 500ms thay vì chờ 5+ giây để nhận toàn bộ response.
Bước 5: Phân Tích Ảnh
Phân tích ảnh là điểm Gemini thực sự nổi bật. Truyền một ảnh cùng với câu hỏi và nhận lại phân tích chi tiết.
import os
import httpx
from google import genai
from google.genai import types
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
# Tải ảnh từ URL
image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/1/12/ThreeTimesMooresTrees.png/1280px-ThreeTimesMooresTrees.png"
image_bytes = httpx.get(image_url).content
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=[
types.Part.from_bytes(data=image_bytes, mime_type="image/png"),
"Biểu đồ này thể hiện điều gì? Tóm tắt trong 2 câu."
]
)
print(response.text)Bạn cũng có thể tải ảnh từ ổ đĩa cục bộ:
with open("screenshot.png", "rb") as f:
image_bytes = f.read()
# Sau đó dùng Part.from_bytes như trênBước 6: Chat Nhiều Lượt
Xây dựng chatbot đòi hỏi quản lý lịch sử hội thoại. SDK xử lý điều này tự động:
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
chat = client.chats.create(model="gemini-2.0-flash")
# Lượt đầu tiên
response = chat.send_message("Tôi đang xây dựng ứng dụng FastAPI. Cần thiết lập tối thiểu những gì?")
print("Gemini:", response.text)
# Lượt thứ hai — Gemini nhớ ngữ cảnh trước đó
response = chat.send_message("Làm thế nào để thêm xác thực JWT vào đó?")
print("Gemini:", response.text)Đối tượng chat tự động duy trì lịch sử hội thoại. Bạn không cần tự theo dõi và gửi lại các tin nhắn trước đó.
Bước 7: Kiểm Soát Output
Các tham số generation cho phép bạn điều chỉnh chính xác cách Gemini phản hồi — ba tham số quan trọng nhất:
from google.genai import types
config = types.GenerateContentConfig(
temperature=0.2, # Thấp hơn = xác định hơn (tốt cho code)
max_output_tokens=512, # Giới hạn độ dài response
system_instruction="Bạn là senior Python developer. Hãy ngắn gọn và trực tiếp."
)
response = client.models.generate_content(
model="gemini-2.0-flash",
contents="Sự khác biệt giữa list và tuple trong Python là gì?",
config=config
)
print(response.text)Các tham số cần biết:
- temperature: 0.0–2.0. Dùng 0.0–0.3 cho tác vụ thực tế/code, 0.7–1.0 cho viết sáng tạo.
- max_output_tokens: Ngăn response quá dài gây tốn chi phí ngoài dự kiến.
- system_instruction: Thiết lập vai trò và hành vi cho mọi tin nhắn trong hội thoại.
Bước 8: Xử Lý Lỗi Đúng Cách
Gọi API có thể thất bại. Rate limit là chuyện thường xảy ra. Luôn bọc lời gọi trong xử lý lỗi:
import os
import time
from google import genai
from google.api_core import exceptions
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
def call_gemini_with_retry(prompt: str, retries: int = 3) -> str:
for attempt in range(retries):
try:
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=prompt
)
return response.text
except exceptions.ResourceExhausted:
wait = 2 ** attempt # exponential backoff
print(f"Bị giới hạn tốc độ. Chờ {wait}s trước khi thử lại...")
time.sleep(wait)
except exceptions.InvalidArgument as e:
print(f"Request không hợp lệ: {e}")
break
return ""
result = call_gemini_with_retry("Giải thích async/await trong Python.")
print(result)Nên Xây Dựng Gì Tiếp Theo
Đã có nền tảng hoạt động rồi. Dưới đây là bốn hướng đáng để phát triển tiếp:
- Hỏi đáp tài liệu: Upload PDF bằng Files API và đặt câu hỏi về nội dung. Gemini 1.5 Pro xử lý đến 1M token, nên ngay cả tài liệu lớn cũng ổn.
- Kiểm duyệt nội dung ảnh: Truyền ảnh do người dùng upload lên Gemini và yêu cầu gắn cờ nội dung không phù hợp trước khi lưu trữ.
- Trợ lý review code: Đẩy git diff vào Gemini với system prompt đóng vai senior reviewer khắt khe.
- Structured output: Dùng
response_mime_type="application/json"trong config để ép output JSON — hữu ích khi bạn cần parse response trong ứng dụng.
Mô Hình Thực Sự Hoạt Động Trong Production
Hãy coi lời gọi AI là một bước trong pipeline — không phải toàn bộ sản phẩm. Quản lý phiên bản prompt của bạn. Log mọi request và response để có thể debug khi có sự cố. Luôn có phương án dự phòng khi API bị ngừng hoạt động.
Bắt đầu với gemini-2.0-flash, đo latency và chất lượng, rồi mới nâng lên Pro nếu Flash thực sự không đáp ứng được yêu cầu của bạn. Đa phần thời gian, nó hoàn toàn đủ dùng.
Google AI Studio playground cũng đáng bookmark — prototype prompt ở đó một cách tương tác trước khi tích hợp vào code. Nó giúp rút ngắn đáng kể vòng lặp thử-sai.
