Decisions API
Model ra quyết định — không sinh văn bản. Bạn gửi dữ liệu (state) kèm một nhóm câu hỏi có kiểu, model trả về đáp án có kiểu kèm xác suất để code rẽ nhánh trực tiếp: có/không, chọn một trong các lựa chọn, hoặc chấm điểm trên thang.
Dùng thay cho bước "hỏi LLM rồi bóc nhãn từ câu trả lời": phân loại ticket, định tuyến yêu cầu, kiểm duyệt nội dung, gắn nhãn hàng loạt, kiểm tra câu trả lời của chatbot, duyệt lệnh của agent… Nhanh (thường dưới 1 giây) và rẻ.
Endpoint
POST https://platform.beeknoee.com/v1/decisions
Bí danh cho TypeSafe SDK: POST https://platform.beeknoee.com/v1/systemone — cùng request, cùng response (xem ví dụ TypeSafe SDK bên dưới).
Request
Headers
| Header | Value | Required |
|---|---|---|
Authorization | Bearer YOUR_API_KEY | ✅ |
Content-Type | application/json | ✅ |
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | ✅ | ID model (VD: typesafe/jev-1.13, liquid/d1, cloudflare/clef) — xem danh sách ở dưới. Nhận cả ID rút gọn kiểu TypeSafe (jev-1.13) và bí danh jev-latest (= bản Jev mới nhất đang bán) |
state | string / object / array | ✅ | Nội dung cần đánh giá: một đoạn chữ, hoặc object/mảng JSON gồm nhiều phần liên quan (tin nhắn, đơn hàng, chính sách…) |
questions | object | ✅ | Map id câu hỏi do bạn đặt → câu hỏi có kiểu (bảng dưới). Đáp án trả về dưới đúng các id đó |
Các trường
user,session_id,trace,provider(một số SDK — VD TypeSafe — gửi kèm) được chấp nhận nhưng bỏ qua — không chuyển đi đâu.
Ba kiểu câu hỏi
type | Hỏi gì | criteria | Trả về |
|---|---|---|---|
noul | Điều kiện có đúng không? | Tuỳ chọn — { "true": "...", "false": "..." } mô tả khi nào là có / không | noul: xác suất có (0–1) |
choice | Chọn MỘT trong các lựa chọn | Bắt buộc — { "lựa_chọn": "mô tả" | null }, tối đa 255 lựa chọn | choice (lựa chọn được chọn), probabilities từng lựa chọn, confidence |
score | Nằm ở đâu trên thang có thứ tự | Bắt buộc — mảng mô tả từng mức, từ thấp → cao, tối đa 10 mức | score (vị trí trung bình theo xác suất, mức đầu = 0), probabilities, confidence, legend |
Mỗi câu hỏi có instructions (bắt buộc): câu hỏi viết bằng lời, hoặc object/mảng JSON nếu muốn ghi luật chi tiết. Với state là object, có thể chỉ thẳng vào một phần bằng đường dẫn, VD: "Does \ticket.messages[0].text` request a refund?"`.
Giới hạn
| Giới hạn | Giá trị |
|---|---|
| Số câu hỏi / request | 64 |
Lựa chọn / câu choice | 255 |
Mức / câu score | 10 |
Kích thước state + questions | 2.000.000 ký tự |
| Ngữ cảnh | theo model (VD Jev 32K token, D1 / Clef 65,5K, Solar Decide 524K) — ghi ở thẻ model |
Models & giá
Danh sách model + giá: Text & Embedding Models → tab Decisions.
Decisions tính tiền theo lượt gọi:
| Loại | Giá | Gồm | Phần vượt |
|---|---|---|---|
| Hầu hết model (Jev, Kev, Tev1, D1, Perplexity Decider, Clef Flash, Span-01) | 5đ / lượt | một số token đầu vào ghi trên thẻ model (VD Jev: 1.700 token) | tính thêm theo token đầu vào — giá / 1M ghi trên thẻ model (đã gồm ưu đãi) |
| Solar Decide | 10đ / lượt | 2.800 token | như trên |
| Clef (27B) | 15đ / lượt | 900 token | như trên |
| Mercury Decide, Span-01 Lite | 5đ / lượt | toàn bộ ngữ cảnh của model | — |
- Đầu ra miễn phí — chỉ tính phần đầu vào (
state+ câu hỏi). - Giá / lượt là giá trọn gói — không cộng thêm gì khác. Giá trên chưa trừ ưu đãi (đang giảm tới 10%). Lượt lỗi không bị trừ tiền.
💡 Gộp câu hỏi để tiết kiệm: mọi câu hỏi trong MỘT request chạy song song và chỉ tính một lượt. Hỏi 10 câu về cùng một
statetrong 1 request = 5đ (miễn tổng token còn trong phần đã gồm của model); tách 10 request = 50đ.
Response
{
"id": "dec-8f3c2a1b-5d7e-4f90-a1b2-c3d4e5f6a7b8",
"object": "decision",
"model": "typesafe/jev-1.13",
"answers": {
"is_bug": { "type": "noul", "noul": 0.96 },
"team": {
"type": "choice",
"choice": "payments",
"confidence": 0.69,
"probabilities": { "payments": 0.8, "frontend": 0.2, "account": 0 }
},
"urgency": {
"type": "score",
"score": 1.99,
"confidence": 0.99,
"probabilities": { "0": 0, "1": 0.01, "2": 0.99 },
"legend": { "0": "Can wait for the next release", "1": "Should be fixed this week", "2": "Blocking revenue right now" }
}
},
"usage": { "input_tokens": 476, "output_tokens": 70 }
}
Cách đọc:
noullà xác suất "có" (0–1).0.5nghĩa là model phân vân, không phải "có một nửa".choicelà lựa chọn được chọn;probabilitiesso các lựa chọn với nhau;confidencecho biết phân bố tập trung tới đâu.scorelà vị trí trên thang (mức đầu tiên = 0).1.99gần như chắc chắn là mức 2.- Tra đáp án theo id câu hỏi — thứ tự các khoá trong
answerskhông cố định. - Chọn ngưỡng (VD tự xử lý khi
confidence ≥ 0.8, còn lại chuyển người) theo cái giá của từng loại sai trong nghiệp vụ của bạn, đừng lấy số tròn.
Ví dụ
cURL
curl https://platform.beeknoee.com/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "typesafe/jev-1.13",
"state": {
"customer_tier": "enterprise",
"ticket": "My checkout page shows a blank screen after I click Pay. I have tried two browsers."
},
"questions": {
"is_bug": {
"type": "noul",
"instructions": "Is the customer reporting a software defect?",
"criteria": {
"true": "The customer describes broken or unexpected product behavior.",
"false": "The customer is asking a question or requesting a feature."
}
},
"team": {
"type": "choice",
"instructions": "Which team should own this ticket?",
"criteria": {
"payments": "Checkout, billing, or payment processing issues.",
"frontend": "Rendering, layout, or browser compatibility issues.",
"account": "Login, permissions, or profile issues."
}
},
"urgency": {
"type": "score",
"instructions": "How urgent is this ticket?",
"criteria": ["Can wait for the next release", "Should be fixed this week", "Blocking revenue right now"]
}
}
}'
Python (tin nhắn tiếng Việt)
import requests
resp = requests.post(
"https://platform.beeknoee.com/v1/decisions",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"model": "liquid/d1",
"state": {"tin_nhan": "Shop ơi em bị trừ tiền 2 lần cho đơn A-104, hoàn lại giúp em khoản thừa nhé, em cần gấp."},
"questions": {
"hoan_tien": {"type": "noul", "instructions": "Khách có yêu cầu hoàn tiền không?"},
"bo_phan": {
"type": "choice",
"instructions": "Bộ phận nào nên xử lý tin nhắn này?",
"criteria": {"thanh_toan": "Trừ tiền, hoàn tiền, hoá đơn", "ky_thuat": "Lỗi web, ứng dụng", "van_chuyen": "Giao hàng"},
},
"muc_do": {"type": "score", "instructions": "Mức độ khẩn cấp?", "criteria": ["Không gấp", "Trong tuần", "Cần xử lý ngay"]},
},
},
timeout=60,
)
a = resp.json()["answers"]
if a["hoan_tien"]["noul"] > 0.8 and a["bo_phan"]["choice"] == "thanh_toan":
print("Chuyển bộ phận thanh toán, mức độ:", round(a["muc_do"]["score"], 1))
Node.js
const res = await fetch('https://platform.beeknoee.com/v1/decisions', {
method: 'POST',
headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
body: JSON.stringify({
model: 'cloudflare/clef-flash',
state: { comment: 'This product broke after two days, total waste of money!' },
questions: {
negative: { type: 'noul', instructions: 'Is the comment negative about the product?' },
topic: { type: 'choice', instructions: 'Main topic?', criteria: { quality: null, price: null, shipping: null } },
},
}),
})
const { answers } = await res.json()
console.log(answers.negative.noul, answers.topic.choice)
TypeSafe SDK
import { TypeSafeClient } from '@typesafe-ai/sdk';
const client = new TypeSafeClient({
apiKey: process.env.BEEKNOEE_API_KEY,
baseURL: 'https://platform.beeknoee.com',
});
const result = await client.systemOne({
model: 'jev-1.13',
state: 'I was charged twice for my subscription.',
questions: {
refund: { type: 'noul', instructions: 'Is the customer asking for money back?' },
},
});
console.log(result.answers.refund);
SDK tự gọi https://platform.beeknoee.com/v1/systemone. ID rút gọn jev-1.13, jev-latest dùng được như trên.
⚠️ Đặt thời gian chờ của SDK ≥ 60 giây. SDK TypeSafe tự gửi lại khi hết giờ chờ (mặc định JS 10 giây / lượt): lượt đầu vẫn có thể chạy xong phía Beeknoee và bị tính tiền, lượt gửi lại bị tính thêm. Model khởi động nguội (VD Solar Decide) có lúc mất ~8 giây.
Lưu ý theo model
- Respan Span-01 / Span-01 Lite: model chấm hành vi trong hội thoại. Chỉ nhận câu
noul(instructions/criteria là chuỗi);statelà chuỗi, hoặc{ "input": [tin nhắn...], "output": { "role": "assistant", "content": "..." } }(mỗi tin nhắn córole+content). Dùng để hỏi "bot có xin lỗi không?", "người dùng có thô lỗ không?"… - Mercury Decide: có hạn mức chung — giờ cao điểm có thể gặp 429; cần ổn định thì chọn model khác.
- Tiếng Việt: model được huấn luyện chủ yếu bằng tiếng Anh nhưng nhận tiếng Việt tốt (Beeknoee đã thử cả 11 model với tin nhắn tiếng Việt — đều trả đúng). Vẫn nên thử trên dữ liệu thật của bạn trước khi đặt ngưỡng.
- Model không giải thích lý do. Cần lời giải thích thì dùng Decisions để quyết, rồi gọi một model chat để viết lời giải thích (hoặc chuyển người khi
confidencethấp).
Lỗi thường gặp
| HTTP | error.code | Ý nghĩa | Trừ tiền? |
|---|---|---|---|
| 400 | invalid_request | Sai khuôn (thiếu state/questions, type lạ, choice thiếu criteria, score quá 10 mức, quá 64 câu…), model từ chối request (VD Respan nhận câu không phải noul), state + câu hỏi dài quá ngữ cảnh, hoặc ID rút gọn trùng nhiều model — message ghi rõ lý do | ❌ Không |
| 400 | insufficient_balance | Số dư không đủ cho ước tính lượt này | ❌ Không |
| 403 | insufficient_permissions | API key bị giới hạn danh sách model, không gồm model này | ❌ Không |
| 404 | model_not_found | Model không có / đã tắt — xem GET /models/decisions (gửi sai tên liên tục ⇒ 429) | ❌ Không |
| 413 | unknown_error (type: server_error) | Request quá lớn với model | ❌ Không |
| 429 | rate_limit_exceeded | Model đang quá tải — thử lại sau Retry-After giây hoặc đổi model | ❌ Không |
| 502 / 503 / 504 | unknown_error (type: server_error) | Model tạm lỗi / hết giờ — thử lại sau | ❌ Không |
Beeknoee tính tiền theo số token đầu vào thật sau khi trả lời xong (đúng số
usage.input_tokens); trước khi gọi chỉ giữ chỗ theo ước tính (nghiêng về dư) rồi nhả lại.
Tiếp theo
- Embeddings · Rerank — Tìm và xếp hạng tài liệu cho RAG
- Chat Completions — Viết lời giải thích sau khi Decisions đã quyết