Cách sử dụng OpenAI Decisions API

Để sử dụng OpenAI Decisions API, hãy gửi yêu cầu POST đến https://api.openai.com/v1/decisions với "model": "gpt-6-luna", một input (văn bản, hình ảnh hoặc cả hai), và một mảng questions trong đó mỗi câu hỏi là một predicate, một choice, hoặc một score. Bạn nhận lại các câu trả lời được phân loại với xác suất thay vì văn bản để phân tích, và bạn trả $0.10 cho mỗi 1 triệu token đầu vào, không tính phí đầu ra, đọc bộ nhớ đệm (cache-read) hoặc ghi bộ nhớ đệm (cache-write). Điểm cuối này đang ở giai đoạn thử nghiệm công khai kể từ ngày 6 tháng 10 năm 2026.

Hướng dẫn này bao gồm việc lấy khóa, cuộc gọi đầu tiên bằng curl, Python và JavaScript, đọc từng loại câu trả lời, ba câu hỏi trên một phiếu hỗ trợ, đầu vào hình ảnh, ngưỡng và thiết lập thử nghiệm trong Apidog. Để biết khi nào nên chọn điểm cuối này, hãy bắt đầu với OpenAI Decisions API là gì.

button

Tổng quan về yêu cầu Decisions API

Trường	Mô tả
`model`	`gpt-6-luna` (mô hình duy nhất có sẵn trong bản beta)
`input`	Một chuỗi, hoặc một mảng các tin nhắn `user` có `content` là một chuỗi hoặc các phần thuộc loại `input_text` và `input_image`
`questions[].type`	`predicate`, `choice`, hoặc `score`
`questions[].instructions`	Bắt buộc; câu hỏi bằng ngôn ngữ tự nhiên
`questions[].name`	Tùy chọn; được lặp lại trong câu trả lời (`null` nếu bỏ qua)
`questions[].choices`	Chỉ cho `choice`; 2 đến 255 đối tượng `unique {value, description}`, `value` là một chuỗi hoặc boolean
`questions[].levels`	Chỉ cho `score`; các đối tượng `{label, description}` được sắp xếp, thấp nhất trước, chỉ số từ 0
`safety_identifier`	ID người dùng cuối mờ tùy chọn, tối đa 128 ký tự

Nguồn: Tài liệu tham khảo Decisions API. Không có temperature, stream, tools hay text.format trên điểm cuối này.

Lấy khóa và thực hiện cuộc gọi đầu tiên

Tạo một khóa trong bảng điều khiển OpenAI (hướng dẫn khóa API OpenAI có đề cập), xuất nó dưới dạng OPENAI_API_KEY, và không bao giờ dán nó vào mã. Sau đó, đặt một câu hỏi có/không:

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "The box arrived crushed and the screen is cracked.",
    "questions": [
      {"type": "predicate", "name": "damaged",
       "instructions": "Does the customer report a damaged item?"}
    ]
  }'

Phản hồi có ba trường cấp cao nhất: model, answers và usage. Đây là cấu trúc từ tài liệu tham khảo của OpenAI, với output_tokens bằng 0 vì điểm cuối này không tính phí đầu ra:

{
  "model": "gpt-6-luna",
  "answers": [
    {"type": "predicate", "name": "damaged", "probability": 0.95}
  ],
  "usage": {
    "input_tokens": 42,
    "input_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0},
    "output_tokens": 0,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 42
  }
}

Cuộc gọi tương tự trong Python (SDK 3.26.0 trở lên):

from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from the environment

decision = client.decisions.create(
    model="gpt-6-luna",
    input="The box arrived crushed and the screen is cracked.",
    questions=[
        {"type": "predicate", "name": "damaged",
         "instructions": "Does the customer report a damaged item?"}
    ],
)
print(decision.answers[0].probability)

Và trong JavaScript (SDK 7.30.0 trở lên):

import OpenAI from "openai";

const client = new OpenAI();

const decision = await client.decisions.create({
  model: "gpt-6-luna",
  input: "The box arrived crushed and the screen is cracked.",
  questions: [
    { type: "predicate", name: "damaged",
      instructions: "Does the customer report a damaged item?" },
  ],
});
console.log(decision.answers[0].probability);

Đọc câu trả lời theo loại

Các câu trả lời được trả về theo thứ tự bạn đã hỏi, mỗi câu có một type. Hãy chuyển đổi theo loại, vì bất kỳ câu hỏi nào cũng có thể được trả về dưới dạng refusal (từ chối).

predicate trả về probability, một ước tính từ 0 đến 1 rằng điều kiện là đúng.
choice trả về choice (giá trị thắng), probabilities dưới dạng một mảng các đối tượng {value, probability}, và confidence.
score trả về score, probabilities dưới dạng một mảng các đối tượng {value, label, probability} (trong đó value là chỉ số cấp độ dựa trên 0), và confidence. Điểm số là trung bình trọng số xác suất của các chỉ số cấp độ, vì vậy nó có thể nằm giữa các cấp độ: 1.1 có nghĩa là "giữa cấp độ 1 và cấp độ 2, gần 1".
refusal chỉ trả về type và name. Mô hình đã từ chối câu hỏi đó; các câu hỏi khác trong cùng một yêu cầu vẫn có thể nhận được câu trả lời.

for a in decision.answers:
    if a.type == "refusal":
        send_to_review(a.name)
    elif a.type == "predicate":
        flag = a.probability > 0.9
    elif a.type == "choice":
        route = a.choice if a.confidence > 0.8 else "review"
    elif a.type == "score":
        priority = round(a.score)

Hướng dẫn của OpenAI phân biệt như sau: choice cho các danh mục không có thứ tự, chẳng hạn như phòng ban; score cho các cấp độ có thứ tự, chẳng hạn như mức độ nghiêm trọng.

Ba câu hỏi trên một phiếu hỗ trợ

Các câu hỏi độc lập chia sẻ một yêu cầu và một input, và mỗi câu hỏi có thể sử dụng một loại khác nhau. Dưới đây là một predicate, một choice và một score trên một phiếu duy nhất:

{
  "model": "gpt-6-luna",
  "input": "I was charged twice for my order.",
  "questions": [
    {"type": "predicate", "name": "refund_requested",
     "instructions": "Is the customer asking for money back?"},
    {"type": "choice", "name": "department",
     "instructions": "Which team should handle this ticket?",
     "choices": [
       {"value": "billing", "description": "Charges, refunds, invoices"},
       {"value": "technical", "description": "Bugs and errors in the product"},
       {"value": "shipping", "description": "Delivery and tracking"},
       {"value": "other", "description": "Anything else"}
     ]},
    {"type": "score", "name": "urgency",
     "instructions": "How urgent is this ticket?",
     "levels": [
       {"label": "low", "description": "No time pressure"},
       {"label": "medium", "description": "Needs a reply this week"},
       {"label": "high", "description": "Customer is blocked or losing money"}
     ]}
  ]
}

Mảng answers được trả về theo cùng một thứ tự. Các giá trị choice dưới đây là giá trị hướng dẫn của OpenAI cho đầu vào chính xác này; các giá trị predicate và score mang tính minh họa:

"answers": [
  {"type": "predicate", "name": "refund_requested", "probability": 0.88},
  {"type": "choice", "name": "department", "choice": "billing",
   "probabilities": [
     {"value": "billing", "probability": 0.95},
     {"value": "technical", "probability": 0.02},
     {"value": "shipping", "probability": 0.01},
     {"value": "other", "probability": 0.02}
   ],
   "confidence": 0.93},
  {"type": "score", "name": "urgency", "score": 1.6,
   "probabilities": [
     {"value": 0, "label": "low", "probability": 0.05},
     {"value": 1, "label": "medium", "probability": 0.30},
     {"value": 2, "label": "high", "probability": 0.65}
   ],
   "confidence": 0.65}
]

Hai quy tắc từ hướng dẫn: bao gồm một phương án dự phòng như other khi các danh mục của bạn không bao phủ mọi đầu vào, và viết các câu hỏi xoay quanh các tiêu chí có thể quan sát được để các cấp độ điểm liền kề có ý nghĩa khác nhau. Nếu một quyết định thứ hai phụ thuộc vào câu trả lời đầu tiên, hãy gửi một yêu cầu riêng biệt.

Đầu vào hình ảnh

Truyền hình ảnh như một phần nội dung bên trong một tin nhắn user. Hướng dẫn tài liệu về các URL dữ liệu base64 nội tuyến:

{
  "model": "gpt-6-luna",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "Photo attached to a return request."},
      {"type": "input_image", "image_url": "data:image/jpeg;base64,/9j/4AAQ..."}
    ]
  }],
  "questions": [
    {"type": "predicate", "name": "visible_damage",
     "instructions": "Is the product visibly damaged?"}
  ]
}

Tài liệu tham khảo API cũng liệt kê các URL HTTP(S) có thể truy cập công khai, tối đa 128 hình ảnh trên tất cả các tin nhắn trong một yêu cầu, và một trường detail tùy chọn (low, high, auto, original), vì vậy hãy kiểm tra các URL được lưu trữ với tài khoản của riêng bạn trước khi dựa vào chúng. Đầu vào file_id không được hỗ trợ trên cả hai trang.

Chọn ngưỡng từ các ví dụ đã dán nhãn

OpenAI không công bố số liệu về độ chính xác hoặc hiệu chuẩn cho điểm cuối này. Hướng dẫn của họ là sử dụng các ví dụ đã dán nhãn từ ứng dụng của riêng bạn để đặt ngưỡng cho việc định tuyến, lọc hoặc xem xét, dựa trên chi phí của lỗi dương tính giả (false positives) so với lỗi âm tính giả (false negatives). Trên thực tế, điều đó có nghĩa là một tệp CSV nhỏ gồm các phiếu hỗ trợ thực tế với phòng ban mà con người đã chọn, được chạy qua cùng một yêu cầu, để bạn có thể thấy confidence phân tách các tuyến đường rõ ràng khỏi những tuyến đường cần một người. Phần tiếp theo sẽ xây dựng vòng lặp đó.

Kiểm tra Decisions API trong Apidog

Các yêu cầu đã lưu giúp việc điều chỉnh ngưỡng và kiểm tra hồi quy có thể lặp lại. Dưới đây là thiết lập trong Apidog:

Lưu khóa dưới dạng biến môi trường. Tạo một môi trường, thêm OPENAI_API_KEY làm biến bí mật (bài viết Môi trường và biến bí mật của Apidog hướng dẫn thiết lập), và đặt tiêu đề Authorization thành Bearer {{OPENAI_API_KEY}}. Khóa sẽ không bao giờ được đưa vào phần thân yêu cầu được chia sẻ.
Lưu một yêu cầu cho mỗi loại câu hỏi. Tạo một yêu cầu POST đến https://api.openai.com/v1/decisions với Content-Type: application/json, dán câu hỏi choice từ ví dụ phiếu hỗ trợ ở trên vào đó và lưu lại. Sao chép nó cho các phiên bản predicate và score.
Thêm xác nhận JSONPath. Trên yêu cầu choice: trạng thái là 200, $.answers[0].type bằng choice, $.answers[0].choice bằng billing, $.answers[0].confidence lớn hơn 0.8, và $.usage.output_tokens bằng 0. Đối với predicate về thiệt hại, hãy xác nhận $.answers[?(@.name=='damaged')].probability lớn hơn 0.9. Một thay đổi về cách diễn đạt trong hướng dẫn của bạn, hoặc một thay đổi về hành vi của mô hình, giờ đây sẽ làm cho một bài kiểm tra thất bại thay vì định tuyến sai các phiếu hỗ trợ.
Chạy nó trên các phiếu hỗ trợ đã dán nhãn. Xây dựng một kịch bản kiểm thử từ yêu cầu đã lưu và đính kèm một tệp CSV nhỏ với hai cột, ticket_text và expected_department. Ánh xạ {{ticket_text}} vào input và xác nhận $.answers[0].choice bằng {{expected_department}}. Báo cáo chạy hiển thị confidence cho mỗi hàng, đây là dữ liệu mà OpenAI khuyên bạn nên sử dụng để đặt ngưỡng. Điểm mà dưới đó mọi định tuyến sai đều nằm trở thành ngưỡng "định tuyến tự động" trong mã của bạn.
Giả lập mảng answers cho giao diện người dùng. Trỏ bộ định tuyến hoặc giao diện người dùng vào một bản giả lập của cùng một điểm cuối trả về câu trả lời choice với confidence trên và dưới ngưỡng của bạn, cộng với một refusal, để đường dẫn hàng đợi xem xét được xây dựng trước khi bạn tiêu tốn một token đầu vào. Phản hồi giả lập có điều kiện trong Apidog đề cập đến việc chuyển đổi các bản giả lập dựa trên nội dung yêu cầu.
Chạy kịch bản trong CI. Xuất một mã thông báo truy cập, sau đó thêm một bước vào quy trình của bạn:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" -e "$ENV_ID" -r cli,junit

Một xác nhận thất bại sẽ làm cho bản dựng thất bại, vì vậy một sự sụt giảm âm thầm trong confidence sẽ được phát hiện trước khi triển khai thay vì trong hàng đợi hỗ trợ. Để biết các mẫu rộng hơn, hãy xem kiểm thử ứng dụng LLM.

Xử lý lỗi và các trường hợp biên

429 vượt quá giới hạn tốc độ (rate limited). Không có giới hạn cụ thể nào cho Decisions được công bố; hãy kiểm tra Cài đặt > Tổ chức > Giới hạn để biết số liệu của bạn. Hãy lùi lại theo cấp số nhân và tuân thủ tiêu đề Retry-After khi có mặt. Hướng dẫn về việc vượt quá giới hạn tốc độ có một bộ đệm thử lại.
Câu trả lời từ chối. Coi type: "refusal" là một kết quả định tuyến, không phải là một ngoại lệ. Gửi phiếu hỗ trợ đó cho con người và giữ các câu trả lời khác từ cùng một yêu cầu.
Các quyết định phụ thuộc. Mỗi câu hỏi được đánh giá độc lập dựa trên đầu vào chung. Bất cứ điều gì phụ thuộc vào một câu trả lời trước đó đều cần yêu cầu riêng.

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

Decisions API có giá bao nhiêu? $0.10 cho mỗi 1 triệu token đầu vào trên gpt-6-luna, không tính phí đầu ra, đọc bộ nhớ đệm hoặc ghi bộ nhớ đệm. Một phiếu hỗ trợ 500 token với ba câu hỏi có giá 500 / 1.000.000 x $0.10 = $0.00005, vì vậy một triệu phiếu như vậy có giá $50. Đầu vào ngữ cảnh dài hơn 272K token có giá gấp 2 lần, và xử lý theo khu vực cộng thêm 10%.

Decisions API có miễn phí không? Không. Không có tầng miễn phí nào cho Decisions. Nếu bạn muốn thử GPT-6 Luna mà không phải trả tiền, bài viết Các tuyến đường miễn phí của GPT-6 Luna liệt kê những gì tồn tại.

Nó nhanh như thế nào? OpenAI cho biết nhanh hơn khoảng 10 lần so với Responses API và không công bố con số độ trễ tuyệt đối nào. Một nhà phát triển trên diễn đàn OpenAI đã báo cáo các quyết định hình ảnh trong khoảng 0.8 giây.

Những mô hình nào hoạt động với Decisions API? Hiện tại chỉ có gpt-6-luna. Đây là một điểm cuối trên Luna, không phải là một mô hình riêng biệt. Xem GPT-6 Luna là gì để biết về mô hình này.

Khi nào tôi nên sử dụng Structured Outputs thay thế? Khi bạn cần một đối tượng trong lược đồ JSON của riêng mình, chẳng hạn như các trường được trích xuất hoặc một giải thích bằng văn bản, hoặc gọi hàm khi mô hình nên yêu cầu một công cụ với các đối số. Bài viết Decisions API vs Responses API trình bày cùng một phiếu hỗ trợ được thực hiện theo cả hai cách.

Nó so sánh với Jev như thế nào? Cả hai đều trả về các câu trả lời được phân loại với xác suất và chỉ tính phí đầu vào; Jev chỉ hỗ trợ văn bản với giá $0.042 cho mỗi 1 triệu. So sánh Decisions API vs Jev có bảng đầy đủ.

Bước tiếp theo

Gửi yêu cầu phiếu hỗ trợ ba câu hỏi từ hướng dẫn này, sau đó chạy nó trên 20 phiếu hỗ trợ đã dán nhãn của riêng bạn và xem confidence phân tách các tuyến đường chính xác khỏi các tuyến đường sai ở đâu. Sau đó tải xuống Apidog để giữ yêu cầu, kịch bản CSV và các xác nhận lại với nhau, để ngưỡng bạn chọn hôm nay được kiểm tra lại trên mỗi lần triển khai.