پرسش‌ها (پریمیتیوها) › مستندات Jev

Choice choice

انتخاب یک گزینه از مجموعه‌ای تعریف‌شده؛ همراه با احتمال هر گزینه و اطمینان.

آخرین به‌روزرسانی: مدل: jev-1.13.0 منبع بازبینی‌شده در منبع انگلیسی

وقتی پاسخ یکی از مجموعه‌ای ثابت از گزینه‌هاست از Choice استفاده کنید: کدام تیم به تیکت رسیدگی کند، محصول در کدام دسته است یا قطعه‌کد به چه زبانی نوشته شده. اگر پاسخ موقعیتی روی طیف است از Score و اگر بله/خیر است از Noul استفاده کنید.

"What programming language is this code written in"
  → options: python, javascript, typescript, go, rust, other
"What type of meeting is this based on the title and description"
  → options: standup, planning, retrospective, one on one, brainstorm, none of the above
"Which product category does this item belong to"
  → options: electronics, clothing, home garden, food and beverage

ساختار درخواست

type"choice"الزامی

همیشه "choice".

instructionsstring | object | arrayالزامی

پرسشی که مدل پاسخ می‌دهد.

criteriamap<string, string | object | array | null>الزامی

گزینه‌ها به‌صورت نگاشت: هر کلید نام گزینه و هر مقدار توصیف آن. وقتی گزینه به توضیح نیاز ندارد null بگذارید. حداکثر ۲۵۵ گزینه.

شناسه‌ی پرسش را خودتان انتخاب می‌کنید و مدل هرگز آن را نمی‌بیند. هم نام گزینه‌ها و هم توصیفشان به مدل فرستاده می‌شود، پس توصیف‌هایی بنویسید که گزینه‌ها را از هم جدا کنند.

from typesafe_sdk import Choice, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="My running shoes arrived in the wrong size. Can I swap them for a size 10?",
        questions={
            "department": Choice(
                instructions="Which team should handle this?",
                criteria={
                    "returns": "Exchanges, wrong or damaged items",
                    "shipping": "Delivery status, delays, lost packages",
                    "billing": "Charges, invoices, payment problems",
                },
            ),
        },
    )
    print(response.answers["department"].choice)

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();
const response = await client.systemOne({
  state: "My running shoes arrived in the wrong size. Can I swap them for a size 10?",
  questions: {
    department: choice("Which team should handle this?", {
      returns: "Exchanges, wrong or damaged items",
      shipping: "Delivery status, delays, lost packages",
      billing: "Charges, invoices, payment problems",
    }),
  },
});
console.log(response.answers.department.choice);

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "returns",
      "confidence": 1.0,
      "probabilities": {
        "shipping": 0.0,
        "returns": 1.0,
        "billing": 0.0
      }
    }
  },
  "usage": {
    "input_tokens": 328,
    "output_tokens": 34
  }
}

ساختار پاسخ

choice: گزینه‌ای با بیشترین احتمال.
probabilities: توزیع کامل احتمال روی همه‌ی گزینه‌ها؛ مجموع مقادیر ۱ است.
confidence: عددی بین ۰ و ۱ که از پراکندگی probabilities محاسبه می‌شود. توزیع تخت (احتمال پخش بین چند گزینه) یعنی اطمینان پایین؛ یک قله روی یک گزینه یعنی اطمینان بالا.

این تیکت ساده است، پس همه‌ی احتمال روی returns است و اطمینان ۱٫۰. تیکتی که هم به سایز اشتباه و هم به بازپرداخت از دست‌رفته اشاره کند احتمال را بین returns و billing تقسیم می‌کند و اطمینان پایین می‌آید.

روش خوب: در هر فراخوانی بیش از یک پرسش

همه‌ی پرسش‌های Choice مورد نیاز را در یک درخواست بفرستید. همین منطق درباره‌ی گزینه‌های یک Choice هم صدق می‌کند: Choice تا ۲۵۵ گزینه می‌پذیرد و هر گزینه فقط چند توکن هزینه دارد؛ پس فهرست کامل تیم‌ها، دسته‌ها یا محصولات را بدهید نه فهرست کوتاه‌شده. برای طبقه‌بندی در یک سلسله‌مراتب عمیق، Choiceها را سطح‌به‌سطح زنجیر کنید.

یک مثال پیچیده‌تر

تیکتی مبهم‌تر که به سه تیم مربوط است و نمی‌گوید مشتری چه می‌خواهد، با پنج پرسش Choice. دو پرسش گمانه‌زنانه‌اند: return_reason فقط اگر بخش returns باشد و shipping_issue فقط اگر shipping باشد اهمیت دارد. پرسش tone توصیف‌های null دارد چون نام گزینه‌ها گویاست.

from typesafe_sdk import Choice, TypeSafeClient

TRIAGE_QUESTIONS = {
    "department": Choice(
        instructions="Which team should handle this?",
        criteria={
            "returns": "Exchanges, wrong or damaged items",
            "shipping": "Delivery status, delays, lost packages",
            "billing": "Charges, invoices, payment problems",
        },
    ),
    "return_reason": Choice(
        instructions="If the customer wants to return something, why?",
        criteria={
            "wrong_size": "The item doesn't fit",
            "wrong_item": "A different product was delivered",
            "damaged": "The item arrived broken or faulty",
            "changed_mind": "The item is fine, the customer no longer wants it",
            "other": "A return reason that fits none of the above",
        },
    ),
    "shipping_issue": Choice(
        instructions="If this is a shipping problem, which kind is it?",
        criteria={
            "not_delivered": "The package never arrived",
            "delayed": "The package is late but still on its way",
            "wrong_address": "The package went to the wrong place",
            "damaged_in_transit": "The package arrived damaged",
            "other": "A shipping problem that fits none of the above",
        },
    ),
    "requested_resolution": Choice(
        instructions="What does the customer want to happen?",
        criteria={
            "exchange": "Swap the item for a different one",
            "refund": "Money back",
            "replacement": "The same item sent again",
            "information": "Just an answer, no action needed",
        },
    ),
    "tone": Choice(
        instructions="What is the customer's tone?",
        criteria={"calm": None, "frustrated": None, "angry": None},
    ),
}


def triage(ticket: str) -> None:
    with TypeSafeClient() as client:
        response = client.system_one(state=ticket, questions=TRIAGE_QUESTIONS)

    answers = response.answers
    department = answers["department"]

    if department.confidence < 0.3:
        # معلوم نیست به کدام تیم برود؛ یک انسان تصمیم بگیرد
        send_to_manual_triage(ticket)
        return

    if department.choice == "returns":
        assign(ticket, team="returns", issue=answers["return_reason"].choice)
    elif department.choice == "shipping":
        assign(ticket, team="shipping", issue=answers["shipping_issue"].choice)
    else:
        assign(ticket, team="billing")

    # تیم دومی که سهم واقعی از احتمال دارد یک نسخه دریافت می‌کند
    for team, probability in department.probabilities.items():
        if team != department.choice and probability > 0.25:
            notify(ticket, team=team)

    resolution = answers["requested_resolution"]
    if resolution.confidence < 0.5:
        # مشتری نگفته چه می‌خواهد. بپرس، حدس نزن.
        ask_customer_what_they_want(ticket)
    elif resolution.choice == "refund":
        flag_for_refund_approval(ticket)

    if answers["tone"].choice == "angry":
        flag_for_senior_agent(ticket)

در پاسخ ثبت‌شده‌ی مستندات رسمی، department برابر returns با احتمال ۰٫۶۱ است اما billing به‌خاطر شارژ دوباره ۰٫۳۵ گرفته و اطمینان ۰٫۴۲ است؛ requested_resolution با اطمینان ۰٫۲۰ به سمت refund متمایل است. بنابراین کد تیکت را به تیم returns می‌دهد، نسخه‌ای برای billing می‌فرستد (۰٫۳۵ بیشتر از آستانه‌ی ۰٫۲۵) و از مشتری می‌پرسد چه می‌خواهد. یک درخواست، پنج پاسخ و منطق مسیریابی فقط چند if معمولی.

دستورالعمل و معیارهای ساختاریافته

با یک توصیف یک‌خطی برای هر گزینه شروع کنید. وقتی دو گزینه شبیه‌اند و مدل مدام اشتباهشان می‌گیرد، هر کدام را با یک شیء توصیف کنید: چه چیزی را پوشش می‌دهد، چه چیزی متعلق به گزینه‌ی همسایه است و چند ورودی نمونه.

"criteria": {
  "return_policy": {
    "what": "Questions about the rules: return windows, eligibility, fees",
    "not_for": "Checking where a specific return or refund currently is",
    "examples": ["How long do I have to return shoes?", "Do you charge for returns?"]
  },
  "return_status": {
    "what": "Tracking an existing return or refund",
    "not_for": "General questions about what the policy allows",
    "examples": ["I sent my return last week, where's my refund?"]
  }
}

نام فیلدهایی مثل question، focus، what، not_for و examples جزو API نیستند و رزرو نشده‌اند؛ خودتان انتخابشان می‌کنید. مدل نام‌ها را همراه مقادیر می‌بیند، پس از نام‌های کوتاه و گویا استفاده کنید.