Gemini 4 Argon API: Python, luồng và lịch sử hội thoại

Cuộc trò chuyện qua API Gemini 4 Argon dùng nội dung theo định dạng gốc của Gemini: contents, vai trò và parts. Yêu cầu đầu tiên khá nhỏ. Phần khó hơn là giữ lại phản hồi đúng cách trước khi gửi câu hỏi tiếp theo. Dựng lại một lượt của mô hình chỉ từ văn bản hiển thị có thể làm mất nội dung có chữ ký; thêm một tin nhắn trống dùng để báo đang tải vào lịch sử có thể khiến yêu cầu kế tiếp không hợp lệ.

Hướng dẫn này dùng thư viện chuẩn của Python và điểm cuối gốc của SeedRouter, tập trung vào trò chuyện văn bản và truyền theo luồng. Tài liệu tham khảo API đầy đủ mô tả toàn bộ quy cách tham số; bài viết này đi từ một yêu cầu đến một cuộc trò chuyện có thể sử dụng được.

Trước yêu cầu đầu tiên

Bạn cần Python 3, khóa API SeedRouter và đủ số dư tài khoản. Giữ khóa trong biến môi trường có tên SEEDROUTER_API_KEY; không đưa khóa vào mã nguồn hay gói mã gửi đến trình duyệt. Mỗi tin nhắn bạn gửi đều có thể phát sinh phí. Ví dụ không tự động thử lại yêu cầu hoặc gọi yêu cầu tiếp tục.

Mã mô hình là gemini-4-argon và được đặt trong đường dẫn của điểm cuối. Google mô tả định dạng này trong hướng dẫn tạo nội dung gốc. SeedRouter dùng xác thực Bearer như minh họa bên dưới.

Gửi một yêu cầu đến API Gemini 4 Argon

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

Phản hồi là chuỗi sự kiện do máy chủ gửi, không phải một tài liệu JSON duy nhất. Mỗi sự kiện data: chứa JSON theo định dạng gốc của Gemini. Văn bản hiển thị nằm trong candidates[].content.parts[].text; một số phần lại chứa suy luận hoặc chữ ký. usageMetadata có thể đến riêng với văn bản, vì vậy hãy đọc đến sự kiện cuối cùng trước khi coi câu trả lời là hoàn tất.

Ngân sách đầu ra được cố ý đặt nhỏ để kiểm tra hoạt động cơ bản. Suy luận cũng tiêu thụ ngân sách này nên phản hồi có thể chưa hoàn chỉnh. Hãy chủ động tăng ngân sách cho việc khó hơn; đừng biến một câu trả lời chưa hoàn chỉnh thành vòng lặp thử lại mà người dùng không biết.

Chạy cuộc trò chuyện hai lượt bằng Python

Tải ví dụ Python đầy đủ, lưu trên máy rồi chạy:

python3 gemini-4-argon-chat.py

Hỏi “Explain a mutex in one sentence”, sau đó hỏi “Give a Python example of that idea”. Tập lệnh chờ bạn nhập trước mỗi yêu cầu. Nhập một dòng trống để kết thúc. Quy tắc cốt lõi khi lưu lịch sử là:

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

Tập lệnh tải xuống cũng cung cấp thiết lập tạo nội dung, phân tích khung SSE, chỉ in văn bản không phải suy luận và chỉ ghi nhận lịch sử sau lý do kết thúc STOP với parts không trống. Lỗi API, luồng bị ngắt hoặc câu trả lời trống đều giữ nguyên lịch sử trước đó. Tập lệnh không âm thầm gửi lại tin nhắn.

Đoạn mã ngắn ở trên giải thích cấu trúc dữ liệu; hãy chạy toàn bộ tệp để có đủ phần xử lý yêu cầu. Với phản hồi không truyền theo luồng, thao tác tương ứng là generateContent, và các ví dụ tham khảo minh họa cURL, Python, Node.js và Go.

Giữ parts gốc, không lưu chỉ báo đang tải

Yêu cầu thứ hai phải chứa ba lượt thực: tin nhắn người dùng đầu tiên, phản hồi đã hoàn tất của mô hình và tin nhắn người dùng thứ hai. Dòng “Đang suy nghĩ…” trên giao diện không phải một lượt khác của mô hình.

Lỗi như contents.3.parts: Too small: expected array to have >=1 items nghĩa là mục nội dung thứ tư có mảng parts trống. Chỉ số bắt đầu từ 0. Hãy kiểm tra cách dựng lịch sử trước khi đổi prompt hoặc mô hình. Chỉ báo đang tải thuộc trạng thái hiển thị; nó không bao giờ được trở thành { "role": "model", "parts": [] } trong yêu cầu.

Giữ mọi phần trả về đúng thứ tự, bao gồm thoughtSignature và các phần được đánh dấu là suy luận, ngay cả khi giao diện ẩn chúng. Hướng dẫn về chữ ký suy luận của Google giải thích vì sao các trường không thể diễn giải này phải được giữ sang lượt sau. Không chỉnh sửa, bịa ra hay dựng lại chữ ký. Lưu lịch sử gốc riêng với văn bản hiển thị trên giao diện.

Nguyên tắc giữ nguyên nội dung cũng áp dụng cho hội thoại dùng công cụ, nhưng thực thi công cụ và trả kết quả đòi hỏi một vòng lặp ứng dụng lớn hơn. Ví dụ văn bản này không triển khai vòng lặp đó và không nên được giới thiệu là một tác nhân lập trình hoàn chỉnh.

Đọc mức sử dụng và xử lý việc dừng

Với yêu cầu trực tiếp, giữ các giá trị sử dụng mới nhất mà luồng báo về. Không cộng các giá trị tích lũy được báo lặp lại trong cùng một yêu cầu. Đầu vào thông thường bằng promptTokenCount trừ cachedContentTokenCount; đầu ra tính phí bao gồm cả candidatesTokenCount lẫn thoughtsTokenCount. Hướng dẫn giá chuyển các số đếm này thành ngân sách.

Ctrl+C dừng ví dụ và không gửi thêm yêu cầu. Dừng đọc cục bộ không chứng minh rằng quá trình tạo nội dung từ xa không dùng token. Nếu luồng kết thúc trước khi số liệu sử dụng đến, hãy xem bản ghi sử dụng trong tài khoản. Ví dụ thận trọng loại lượt chưa hoàn tất khỏi lịch sử sau này; giữ lại câu trả lời một phần là quyết định riêng khi thiết kế ứng dụng.

Long decode là một trường hợp khác. Lý do kết thúc CONTINUATION dùng token tiếp tục để khôi phục quá trình tạo nội dung ban đầu; đó không phải tin nhắn mới của người dùng. Google yêu cầu nội dung yêu cầu gốc và token mới nhất, không nối đầu ra một phần vào contents. Xem hướng dẫn long decode. Tập lệnh nhập môn này dừng lại thay vì tự động triển khai việc tiếp tục.

Những gì đã được xác minh?

Truyền văn bản cơ bản theo luồng đã vượt qua kiểm tra toàn trình cục bộ qua Playground của SeedRouter. Phần phân tích và quản lý lịch sử trong ví dụ được kiểm tra bằng luồng tổng hợp, bao gồm phần có chữ ký, phản hồi trống và các lần ngắt. Đây là dữ liệu kiểm tra phần mềm, không phải các lần chạy mô hình bổ sung. Công cụ, nội dung đa phương tiện và tiếp tục vẫn cần được kiểm tra riêng trước khi mô tả là các tích hợp đã xác minh.

Câu hỏi về API

Có thể thay tên mô hình OpenAI bằng `gemini-4-argon` không?

Chỉ thay tên không chuyển đổi định dạng tin nhắn. Hướng dẫn này dùng contents và parts theo định dạng gốc của Gemini. Hãy xác nhận ứng dụng khách hỗ trợ giao thức đó cùng cách xác thực và điểm cuối bạn cấu hình.

Vì sao câu trả lời trống dù đã dùng token?

Suy luận có thể tiêu thụ hết ngân sách đầu ra; thiết lập an toàn hoặc quá trình tạo nội dung chưa hoàn tất cũng có thể khiến không có văn bản hiển thị. Hãy xem lý do kết thúc và mức sử dụng. Không chèn một lượt mô hình trống hoặc tự động lặp lại yêu cầu trả phí.

Ngữ cảnh một triệu token có nghĩa là một triệu token đầu ra không?

Không. Đầu vào, suy luận và đầu ra dùng chung ngữ cảnh. Các lượt tạo nội dung dài cũng có giới hạn theo yêu cầu và có thể cần tiếp tục. Hãy lập ngân sách cho tổng lượng dùng chung, không phải hai hạn mức đầu vào và đầu ra riêng biệt.

Thêm tính năng sau khi cuộc trò chuyện hoạt động

Bắt đầu bằng một câu trả lời hoàn chỉnh, sau đó xác nhận lượt thứ hai nhận được nội dung gốc ban đầu. Giữ lịch sử API Gemini 4 Argon tách khỏi trạng thái hiển thị khi thêm tệp đính kèm, công cụ hoặc lưu trữ lâu dài. Playground của mô hình và hướng dẫn truy cập là bước tiếp theo để sử dụng tương tác và tìm hiểu yêu cầu tài khoản.

Gemini 4 Argon API: trò chuyện Python với luồng theo định dạng gốc