Cách sử dụng Gemini Decisions API

Để sử dụng Gemini Decisions API, hãy tạo một key trong Google AI Studio, cài đặt google-genai phiên bản 3.2 trở lên, và gọi client.decisions.create() với model gemini-decision-1, một input dùng chung, và một map các questions có định kiểu (noul, choice hoặc score). Bạn sẽ nhận về một xác suất đã hiệu chỉnh và một giá trị confidence cho mỗi câu hỏi, với số token đầu ra bằng không.

Bên dưới: từng bước bằng Python, JavaScript và REST, từ câu hỏi có/không đầu tiên đến định tuyến theo confidence và bộ kiểm thử CI.

Gemini Decisions API là gì?

Gemini Decisions API là một endpoint trong Gemini Developer API (v1beta) trả lời các câu hỏi tập đóng thay vì sinh văn bản. Bạn gửi một đầu vào đa phương thức và tối đa 1.000 câu hỏi độc lập. Model gemini-decision-1 chấm điểm mọi lựa chọn trong một lần truyền duy nhất và trả về các xác suất đã hiệu chỉnh mà code của bạn có thể dùng để rẽ nhánh trực tiếp.

Google công bố nó vào ngày 11 tháng 11 năm 2026. Tài liệu chính thức định nghĩa ba loại câu hỏi:

Theo trang định giá Gemini API, giá là 0,10 USD cho mỗi 1 triệu token đầu vào và 0 USD cho đầu ra. Đầu vào dùng chung chỉ được tính tiền một lần cho mỗi yêu cầu, bất kể bạn hỏi bao nhiêu câu hỏi. Nếu bạn đã đọc hướng dẫn của chúng tôi về cách sử dụng OpenAI Decisions API, cấu trúc sẽ nghe quen thuộc, nhưng các trường bên dưới là của riêng Gemini.

Bước 1: Tạo API key và cài đặt SDK

1. Mở Google AI Studio và tạo một API key.
2. Xuất nó ra: export GEMINI_API_KEY="your-key".
3. Cài đặt SDK 3.2 trở lên: pip install -U google-genai hoặc npm install @google/genai@latest.

Bạn có thể thử các câu hỏi mà không cần code trước trong Decisions Playground, nơi có thể xuất code chạy được.

Gói miễn phí, kiểm tra ngày 12 tháng 11 năm 2026: trang giới hạn tốc độ liệt kê 200 yêu cầu mỗi phút, 50.000 token mỗi phút và 10.000 yêu cầu mỗi ngày ở gói Free. Đầu vào được miễn phí ở đó, nhưng trang định giá đánh dấu dữ liệu của gói Free là "Được dùng để cải thiện sản phẩm của chúng tôi: Có", vì vậy hãy giữ dữ liệu khách hàng thực trên gói trả phí. Để biết thêm về hạn mức miễn phí của Google, xem hướng dẫn gói miễn phí Gemini API của chúng tôi.

Bước 2: Đặt câu hỏi noul (có/không) đầu tiên

Một câu hỏi noul trả về xác suất rằng câu trả lời là "có". Lưu ý phiên bản API v1beta: endpoint không có trên v1.

Python:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
    questions={
        "is_damaged": {
            "type": "noul",
            "instructions": "Did the item arrive damaged?",
        },
    },
)

answer = result.answers["is_damaged"]
print(f"P(yes)={answer.noul:.2f} confidence={answer.confidence:.2f}")

JavaScript:

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: "The blue mug I ordered on Monday arrived cracked on Wednesday.",
  questions: {
    is_damaged: { type: "noul", instructions: "Did the item arrive damaged?" },
  },
});

const answer = result.answers?.is_damaged;
if (answer?.type === "noul") console.log(answer.noul, answer.confidence);

REST:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": "The blue mug I ordered on Monday arrived cracked on Wednesday.",
    "questions": {
      "is_damaged": { "type": "noul", "instructions": "Did the item arrive damaged?" }
    }
  }'

Tài liệu của Google hiển thị phản hồi này (ví dụ từ tài liệu, không phải từ lần chạy của chúng tôi):

{
  "answers": { "is_damaged": { "type": "noul", "noul": 0.99, "confidence": 0.99 } },
  "usage": { "total_input_tokens": 100, "total_output_tokens": 0, "total_tokens": 100 }
}

Khi "có" mơ hồ, hãy thêm criteria với true_description và false_description. Một quy tắc cần nhớ: giá trị noul luôn nằm giữa 0.01 và 0.99, vì vậy một ngưỡng trên 0.99 sẽ không bao giờ khớp.

Bước 3: Thêm câu hỏi choice và score

Đặt các câu hỏi độc lập về cùng một đầu vào vào một yêu cầu. Đầu vào chỉ được tính tiền một lần; mỗi câu hỏi chỉ thêm token của chính nó.

result = client.decisions.create(
    model="gemini-decision-1",
    input="I was charged twice for my order and the export page crashes in Safari.",
    questions={
        "department": {
            "type": "choice",
            "instructions": "Which department should handle this request?",
            "criteria": {
                "billing": "Payments, invoices, and refunds.",
                "technical": "Problems using the product.",
                "shipping": "Delivery and tracking.",
                "other": "Anything outside these categories.",
            },
        },
        "severity": {
            "type": "score",
            "instructions": "How severe is this issue for the user?",
            "criteria": [
                "Cosmetic: appearance only, no lost functionality.",
                "Workaround available: a task fails, but another way works.",
                "Fully blocked: a task fails with no workaround.",
            ],
        },
    },
)

Ba chi tiết trong tài liệu hay khiến mọi người vấp:

• Các key của choice được sắp xếp theo bảng chữ cái trước khi chấm điểm. Dùng other làm phương án bắt-all, đừng dùng none_of_the_above, vì nó sắp xếp trước các phương án thực.
• Criteria của score là một danh sách, sắp xếp từ thấp nhất đến cao nhất và đánh chỉ mục từ 0. score trả về là trung bình có trọng số theo xác suất, nên nó có thể nằm giữa các mức (tài liệu hiển thị 1.12).
• Model không bao giờ nhìn thấy key câu hỏi của bạn. Hãy viết câu hỏi đầy đủ trong instructions.

Để lấy một mức rời rạc từ score, hãy lấy phần tử có xác suất cao nhất:

sev = result.answers["severity"]
level = max(sev.probabilities, key=sev.probabilities.get)
print(sev.legend[level])

Bước 4: Gửi ảnh, PDF và âm thanh

input nhận một chuỗi, một khối nội dung hoặc danh sách các khối, theo cùng định dạng khối với Interactions API. Các khối được hỗ trợ là text, image, audio, video và document (chỉ PDF).

import base64

with open("earcup.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")
with open("return-form.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode("utf-8")

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {"type": "text", "text": "Customer photo and form for return #8821.\n"},
        {"type": "image", "data": image_b64, "mime_type": "image/jpeg", "resolution": "low"},
        {"type": "document", "data": pdf_b64, "mime_type": "application/pdf"},
    ],
    questions={
        "visible_damage": {
            "type": "noul",
            "instructions": "Does the photo show physical damage to the device? Ignore the packaging.",
        },
        "form_signed": {
            "type": "noul",
            "instructions": "Is the return form in the PDF signed by the customer?",
        },
    },
)

Với âm thanh, truyền một khối như {"type": "audio", "uri": "<https-url>", "mime_type": "audio/mp3"}. Những giới hạn đáng biết:

• Dữ liệu base64 nội tuyến bị giới hạn ở 100 MB mỗi yêu cầu (50 MB với PDF); URL bên ngoài giới hạn 15 MB mỗi cái.
• Đặt đúng MIME type thực tế. API từ chối application/octet-stream.
• URL YouTube và URI gs:// không được hỗ trợ. Dùng Files API, một URL HTTPS công khai hoặc có chữ ký, hoặc byte nội tuyến.
• resolution (low, medium, high, ultra_high) đổi chi tiết hình ảnh lấy số token. ultra_high chỉ dành cho ảnh.

Bước 5: Đọc xác suất và confidence

Mỗi câu trả lời đều mang một giá trị confidence từ 0 đến 1, là xác suất ước tính rằng câu trả lời hàng đầu đúng. Với choice và score, nó bằng xác suất của kết quả hàng đầu. Với noul, nó là max(noul, 1 - noul).

Vậy một noul bằng 0.03 có confidence là 0.97: model chắc chắn câu trả lời là "không".

Bước 6: Chuyển các câu trả lời có confidence thấp sang phương án dự phòng

Dùng giá trị để chọn hành động, và dùng confidence để quyết định có tự động thực hiện hay không:

a = result.answers
dept = a["department"]

if dept.confidence >= 0.7 and dept.choice != "other":
    route_to(dept.choice)
elif dept.confidence >= 0.4:
    route_to_fallback_model(ticket)   # a bigger model reasons it out
else:
    route_to("human_review")

Các ngưỡng 0.7 và 0.4 chỉ là ví dụ: Google khuyên nên đặt ngưỡng dựa trên các mẫu có nhãn từ lưu lượng thực của bạn. Hai quy tắc nữa từ tài liệu:

• Câu hỏi choice luôn chia xác suất trên các phương án của bạn, kể cả khi không phương án nào phù hợp. Hãy ghép chúng với một kiểm tra phạm vi như "Tin nhắn này có phải về một đơn hàng không?"
• Xem đầu vào là không đáng tin. Tin nhắn của người dùng có thể tự biện hộ cho cách phân loại của nó. Hãy giữ con người hoặc một bước kiểm tra thứ hai đối với các khoản thanh toán và các hành động rủi ro cao khác.

Bước 7: Để coding agent kiểm thử bằng Apidog CLI

Một lớp định tuyến có thể hỏng một cách âm thầm. Ai đó đổi cách diễn đạt một tiêu chí, billing biến thành technical cho một nửa số ticket của bạn, và không có gì báo lỗi. Giải pháp là một bộ kiểm thử hồi quy cố định các quyết định mong đợi, và coding agent của bạn có thể xây dựng nó bằng Apidog CLI trong khi bạn duyệt lại.

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Sau đó đưa cho agent của bạn một prompt:

In Apidog project <id>, build a test suite for POST
https://generativelanguage.googleapis.com/v1beta/decisions (header x-goog-api-key
from env var GEMINI_API_KEY). Add one request per question type (noul, choice,
score) asserting status 200, confidence between 0 and 1 and zero output tokens.
Add a test data set of 20 tickets with expected departments and assert each
choice matches with confidence >= 0.7. Run it and summarize failures.

Agent đọc schema của mỗi payload, kiểm tra tính hợp lệ, viết các tài nguyên và chạy bộ kiểm thử:

apidog cli-schema get test-scenario-create
apidog cli-schema validate test-scenario-create --file scenario.json
apidog test-scenario create --project <id> --file scenario.json
apidog test-data create --project <id> --file tickets.json
apidog test-suite create --project <id> --file suite.json
apidog run --test-suite <suiteId> --project <id> -e <envId> -d <testDataId> -r cli,junit --out-dir reports

Mọi cờ ở trên lấy từ apidog run --help trên CLI 2.2.12. Giờ đây một prompt hoặc tiêu chí bị thay đổi khiến quyết định của một fixture bị lật sẽ làm lần chạy thất bại. Đưa cùng lệnh apidog run ... -r cli,junit vào GitHub Actions và tệp JUnit sẽ hiển thị ticket nào bị lật; hướng dẫn Apidog CLI CI/CD của chúng tôi có tệp workflow, và Apidog CLI trong Claude Code đề cập đến cấu hình agent. Gói Free của Apidog hỗ trợ tối đa 4 người dùng.

Giới hạn và những gì chưa được hỗ trợ

Theo giới hạn của Decisions API, kiểm tra ngày 12 tháng 11 năm 2026:

• 1 đến 1.000 câu hỏi mỗi yêu cầu, trong một cửa sổ ngữ cảnh 262.144 token.
• Không có context caching, không có Batch API, không có suy luận Flex hay Priority. Đầu vào lặp lại giữa các yêu cầu vẫn được tính tiền đầy đủ.
• Khối an toàn (safety) trả về HTTP 400 với error.code như safety hoặc prohibited_content, thay vì một câu trả lời.
• Chỉ có trên Gemini Developer API (v1beta). Google cho biết hỗ trợ Vertex AI "sắp ra mắt", không có ngày cụ thể.

Google báo cáo độ trễ đầu-cuối 150 đến 250 ms, gần như phẳng từ 1 đến 100 câu hỏi với đầu vào tới 16K token, và cho biết Gemini Decision 1 dẫn đầu bộ benchmark của chính hãng với sai số hiệu chỉnh thấp nhất. Đó là những con số của Google; hãy đo độ trễ trên đầu vào của riêng bạn trước khi thiết kế dựa trên chúng.

Câu hỏi thường gặp

Gemini Decisions API có miễn phí không? Có gói Free với đầu vào miễn phí, giới hạn 200 RPM, 50.000 TPM và 10.000 yêu cầu mỗi ngày (kiểm tra ngày 12 tháng 11 năm 2026). Dữ liệu của gói Free có thể được dùng để cải thiện sản phẩm của Google. Gói trả phí có giá 0,10 USD cho mỗi 1 triệu token đầu vào.

noul nghĩa là gì? Đó là loại câu hỏi có/không. Trường noul là xác suất rằng câu trả lời là "có", nằm giữa 0.01 và 0.99.

Tôi cần phiên bản API nào? v1beta. Đặt http_options={"api_version": "v1beta"} trong Python, apiVersion: "v1beta" trong JavaScript, hoặc gọi /v1beta/decisions qua REST.

Nó có hoạt động trên Vertex AI không? Chưa. Nó chỉ có trên Gemini Developer API; Google liệt kê Gemini trong Google Cloud là sắp ra mắt.

Làm sao chọn ngưỡng confidence? Gắn nhãn vài trăm đầu vào thực, chạy chúng qua API, và chọn ngưỡng mà tại đó chi phí của hành động tự động sai cân bằng với chi phí duyệt bởi con người.