دستهبندی خودکار پیام و تیکت با هوش مصنوعی؛ خروجی JSON
پیام و تیکت را با هوش مصنوعی خودکار دستهبندی کنید و از آگهی فیلد بیرون بکشید؛ خروجی JSON سنجیدهشده که با ctx.ai.ask همان لحظه در جدول پروژهتان مینشیند.
در این مطلب
دستهبندی خودکار پیام و تیکت با هوش مصنوعی یعنی هر پیامی که میرسد، بدون اینکه کسی بخواندش، یک برچسب بگیرد: مالی، فنی، فروش، شکایت. همین سازوکار از یک متن آزاد مثل آگهی یا فاکتور هم فیلدهای مشخص بیرون میکشد. شرط بهدردخوردنش یک چیز است: خروجی باید همیشه یکی از برچسبهای شما باشد، یا JSON با همان فیلدهایی که تعریف کردهاید. در فیکارو این همان ایجنت شکلدار است: شکل خروجی را در پنل تعریف میکنید، سرور هر جواب را پیش از تحویل با همان شکل میسنجد، و اگر بکاندتان روی فیکاروست، برچسب همان لحظهی ثبت تیکت با یک خط کد در جدول خودتان مینشیند.
چرا جواب متنی برای دستهبندی کافی نیست؟
اگر از یک مدل گفتوگویی بپرسید «این پیام مالی است یا فنی؟»، ممکن است بنویسد «به نظر میرسد موضوع اصلی پیام مالی باشد». برای آدم جواب خوبی است و برای کد هیچ. کدی که جواب را با برچسب «مالی» مقایسه میکند شکست میخورد و شما میمانید با تحلیل متنی که قرار بود تحلیل را جای شما انجام بدهد.
راهحل این است که خروجی از اول بسته باشد. ایجنت شکلدار در فیکارو دو جور خروجی دارد:
- یک برچسب از فهرست بسته: بین ۲ تا ۳۰ برچسب که خودتان تعریف میکنید.
outputهمیشه یکی از آنهاست. - شیئی با فیلدهای مشخص: تا ۲۰ فیلد از نوع متن، عدد، عدد صحیح یا بولی. فیلد متنی هم میتواند فهرست مقدار مجاز داشته باشد. شیء تخت است و فیلد تودرتو یا آرایه ندارد.
سه راه دستهبندی خودکار متن فارسی
| معیار | کلیدواژه و regex | آموزش مدل طبقهبند | ایجنت با برچسب بسته |
|---|---|---|---|
| آمادهسازی | فهرست کلمه برای هر دسته | صدها نمونهی برچسبخورده | تعریف یکخطی هر برچسب |
| فارسی محاوره و غلط املایی | ضعیف | به دادهی آموزشی بستگی دارد | خوب |
| اضافه کردن دستهی تازه | کلمهی تازه | آموزش دوباره | یک برچسب و یک خط توضیح |
| ذخیرهی برچسب در دیتابیس | کد خودتان | کد و سرور خودتان | یک خط ctx.ai.ask در فانکشن پروژه |
| هزینهی هر پیام | تقریباً صفر | زیرساخت اجرای مدل | هزینهی یک پرسش، به تومان |
| وقتی مطمئن نیست | برچسب اشتباه | برچسب با احتمال پایین | answered برابر false و handoff برابر true |
اگر دستههایتان با چند کلمهی قطعی جدا میشوند، regex ارزانتر است و همان را نگه دارید. وقتی مشتری مینویسد «پولم رفت ولی هیچی ثبت نشد» و هیچ کلمهی «پرداخت» یا «تراکنش» در پیام نیست، فهمیدن معنا لازم است و ایجنت همینجا ارزش دارد.
دستهبندی تیکت با یک برچسب از فهرست بسته
در تب «هوش مصنوعی (AI)» یک ایجنت از قالب دستهبند تیکت و پیام بسازید. برچسبهایش «مالی»، «فنی»، «فروش»، «شکایت» و «سایر» است و تعریف هر کدام در دانستهها آمده. مثلاً «مالی: پرداخت، کسر پول از حساب، بازگشت وجه، فاکتور و صورتحساب». برچسبها و تعریفها را با دستههای واقعی کسبوکارتان عوض کنید؛ اگر راهنمای پشتیبانیتان PDF یا صفحهی سایت است، همان را در دانستهها وارد کنید.
یک تنظیم دیگر هم ارزشش را دارد: در صفحهی «ارجاع به انسان» ایجنت، برچسب «شکایت» را علامت بزنید. از آن به بعد پیامی که این برچسب را بگیرد، و هر پیامی که ایجنت دستهاش را تشخیص ندهد، در پاسخ handoff: true دارد؛ با یک فیلد میفهمید کدام تیکت باید همین حالا به یک آدم برسد. پیش از استفادهی واقعی هم چند ده پیام واقعی را در میز آزمایش بفرستید و برچسب ایجنت را با برچسب خودتان مقایسه کنید.
برچسب در لحظهی ثبت تیکت؛ ctx.ai.ask در فانکشن پروژه
اگر تیکتها در یک پروژهی فیکارو ثبت میشوند، سرور جدا لازم ندارید. اپ یا سایت شما بهجای ساختن مستقیم ردیف، فانکشن new_ticket را صدا میزند. فانکشن تیکت را میسازد، از ایجنت دستهبند میپرسد و برچسب را کنار همان ردیف ذخیره میکند. جدول ticket اینجا دو ستون اضافه دارد: label (متن) و needs_human (بولی).
const AGENT = "<شناسهی ایجنت دستهبند>";
const body = String(ctx.input.body || "").trim();
if (!body) ctx.reject("متن تیکت خالی است");
const t = ctx.db.create("ticket", {
title: ctx.input.title || "",
body: body,
});
let label = null;
let needsHuman = true;
try {
const r = ctx.ai.ask(AGENT, body, { data: { title: t.title } });
if (r.answered) label = r.output;
needsHuman = r.handoff;
} catch (e) {
ctx.log("ایجنت جواب نداد:", e.code);
}
ctx.db.admin.update("ticket", t.id, {
label: label,
needs_human: needsHuman,
});
ctx.respond(201, { id: t.id, label: label });
برای «پولم کسر شده ولی سفارش ثبت نشده» برچسب "مالی" در ردیف مینشیند و needs_human برابر false است. برای پیامی با برچسب «شکایت»، یا پیامی که ایجنت دستهاش را نداند، needs_human برابر true میشود و پنل پشتیبانیتان میتواند همانها را اول نشان بدهد. اگر ایجنت به هر دلیلی جواب ندهد، مثلاً کیف پول خالی باشد، تیکت گم نمیشود: بیبرچسب و با needs_human: true ذخیره میشود و دلیل در گزارش اجرای فانکشن میآید.
ctx.ai.ask همزمان است و await نمیخواهد، و کلید ایجنت لازم ندارد چون ایجنت مال همان حسابی است که پروژه مال اوست. برچسب با ctx.db.admin ذخیره میشود تا اگر در ویرایشگر فیلد، «نوشتن این فیلد» را برای label و needs_human روی «فقط شما (کلید API و ادمین)» بگذارید، فرستندهی تیکت نتواند آنها را خودش پر کند. هر اجرا حداکثر ۲ بار میپرسد، و این کار در فانکشنها ممکن است، نه در قانونها که وسط ذخیرهی ردیف اجرا میشوند. کدهای خطا در راهنمای فانکشنها آمده است.
صدا زدن دستهبند از سرور خودتان
اگر تیکتها جای دیگری ثبت میشوند، همان ایجنت را از سرور خودتان با یک درخواست HTTP و کلید apck_bot_ از متغیر محیطی صدا بزنید:
const BOT_URL = "https://api.fikaro.ir/ai/v1/bots/{botId}/ask";
async function classify(text) {
const res = await fetch(BOT_URL, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TICKET_BOT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ input: text }),
});
const body = await res.json();
if (!res.ok) {
throw new Error(`${body.code} ${body.requestId ?? ""}`);
}
return body.answered ? body.output : null;
}
const QUEUES = { "مالی": "finance", "فنی": "tech", "فروش": "sales" };
const label = await classify("پولم کسر شده ولی سفارش ثبت نشده");
const queue = QUEUES[label] ?? "support";
برای این پیام output برابر "مالی" است. اگر ایجنت نتواند تصمیم بگیرد، output برابر null است و کد بالا پیام را به صف عمومی پشتیبانی میفرستد.
استخراج اطلاعات از متن آزاد با هوش مصنوعی
قالب استخراج فیلد متن آزاد فارسی را به شیئی با فیلدهای شما تبدیل میکند. نمونهی پیشفرضش آگهی ملک است، با فیلدهای city، area، price و rooms. برای ورودی «آپارتمان ۸۵ متری دو خوابه در شیراز، ۴ میلیارد» جواب این است:
{
"answered": true,
"answer": null,
"output": {
"city": "شیراز",
"area": 85,
"price": 4000000000,
"rooms": 2
},
"sources": [],
"requestId": "0199d3b6-5e21-7f08-a3c4-1b7d9e2f6a90",
"handoff": false,
"knowledgeIds": [],
"pendingAction": null
}
دو کار سخت اینجا برای شما انجام شده. «۸۵ متری» و «۴ میلیارد» به عدد خالص تبدیل شدهاند، چون دستورالعمل قالب تبدیل رقم فارسی و واحد را صریح خواسته. و فیلدی که در متن نیامده حدس زده نمیشود: برای «آپارتمان ۱۲۰ متری سه خوابه در اصفهان، نوساز» مقدار price برابر null است، نه یک عدد ساختگی.
همین خروجی را هم میشود مستقیم در جدول نشاند. فانکشن new_listing متن آگهی را میگیرد و یک ردیف با فیلدهای جدا در جدول listing میسازد، تا آگهیها از همان اول با شهر، متراژ و قیمت فیلتر و مرتب شوند:
const AGENT = "<شناسهی ایجنت استخراج>";
const text = String(ctx.input.text || "").trim();
if (!text) ctx.reject("متن آگهی خالی است");
const r = ctx.ai.ask(AGENT, text);
if (!r.answered) ctx.reject("از این متن فیلدی بیرون نیامد");
const o = r.output;
const rec = ctx.db.create("listing", {
raw: text,
city: o.city,
area: o.area,
price: o.price,
rooms: o.rooms,
});
ctx.respond(201, rec);
اینجا خطای ctx.ai.ask را عمداً نگرفتهایم: اگر ایجنت جواب ندهد، فانکشن با 500 function_failed تمام میشود، ردیفی ساخته نمیشود و اپ میتواند همان متن را دوباره بفرستد. وضعیت کیف پول شما هم به صداکننده گفته نمیشود.
همین الگو برای فاکتور، آدرس یا فرم تماس هم کار میکند. فیلدها را عوض کنید و در دستورالعمل بنویسید هر کدام از کجای متن میآید. اگر ورودی ساختاریافته هم دارید، مثلاً شناسهی سفارش کنار متن پیام، آن را در data بفرستید که یک شیء JSON تا ۱۶ کیلوبایت است.
وقتی خروجی با شکل نمیخواند چه میشود؟
سرور هر خروجی را پیش از تحویل با شکل تعریفشده میسنجد: برچسبی بیرون از فهرست، فیلد کم یا اضافه، یا عددی که عدد صحیح نیست هیچوقت به کد شما نمیرسد. اگر مدل جواب خالی، بریده یا نامعتبر بدهد، از API خطای 502 با کد output_invalid میگیرید و در فانکشن، ctx.ai.ask همان کد را پرتاب میکند. این خطا را میشود دوباره فرستاد، ولی آن تلاش هزینه داشته و تلاش بعدی هم دارد.
برای پردازش انبوه، مثلاً برچسب زدن به آرشیو تیکتهای قبلی، سقف نرخ را در نظر بگیرید: بسته به پلن ایجنت از ۲ درخواست در ثانیه برای هر ایجنت، ۵ درخواست در ثانیه برای همهی ایجنتهای یک حساب روی هم، و ۲ پرسش همزمان برای هر حساب. وقتی از آن بگذرید 429 با سرآیند Retry-After میگیرید. پیامها را در صف بگذارید و همانقدر که سرآیند میگوید صبر کنید.
شکل خروجی بخشی از قرارداد API شماست. اگر ایجنت را از متنی به شکلدار، یا
برعکس، تغییر دهید، شکل پاسخ برای همهی کدهایی که صدایش میزنند هم همان لحظه
عوض میشود و answer و output جایشان را عوض میکنند. پنل پیش از ذخیره
هشدار میدهد. برای شکل تازه، ایجنت تازه بسازید و کد را بعد جابهجا کنید.
دستهبند چطور هر روز بهتر میشود؟
هر پرسش، چه از API و چه از فانکشن، یک ردیف در گزارش سؤالهای ایجنت میسازد: متن، برچسب، هزینه و اینکه جواب داده شد یا نه. پیامهایی که ایجنت دستهشان را ندانسته زیر فیلتر «بیجواب» جمع میشوند، و هر روز از ساعت ۹ صبح به وقت تهران، اگر دیروز چنین پیامی بوده، خلاصهاش در زنگولهی پنل میآید. کنار هر کدام دکمهی «افزودن به دانستهها» هست: تعریف دقیقتری برای برچسبی که جا مانده مینویسید و دفعهی بعد ایجنت پیام مشابه را درست دستهبندی میکند. بدون آموزش دوباره، بدون دادهی برچسبخورده.
هزینهی دستهبندی هر پیام چقدر است؟
هر پیام یک پرسش است و بر پایهی هزینهی واقعی مدل برای همان پرسش، به تومان، از کیف پول کم میشود؛ از راه ctx.ai.ask هم همان هزینه را دارد. با مدل پیشفرض پلن شروع کنید و فقط اگر در میز آزمایش برچسبها را درست نزد سراغ مدل قویتر بروید؛ صفحهی «مدل» ایجنت برآورد هزینهی هر جواب را برای هر مدل نشان میدهد. هزینهی ساعتی ایجنت روشن از ۵۰ تومان در ساعت شروع میشود و جدول پلنها در صفحهی قیمتها آمده است.
برای امتحان لازم نیست حتی یک تومان پرداخت کنید: حساب تازه ۵۰۰۰ تومان اعتبار هدیهی هوش مصنوعی دارد که برای دستهبندی چند ده پیام واقعی کافی است، و اعتبار هدیهی ثبتنام هزینهی ساعتی را میدهد.
ایجنت متنی، یعنی چت بات، را در راهنمای ساخت چت بات هوش مصنوعی ساختهایم و فرق این مسیر با خرید دسترسی خام به مدل را در API هوش مصنوعی ایرانی نوشتهایم. فهرست کامل کدهای خطا در راهنمای ایجنتها است.
سوالات متداول
- دستهبندی متن فارسی با هوش مصنوعی چقدر دقیق است؟
- به وضوح تعریف برچسبها بستگی دارد. پیش از استفادهی واقعی چند ده پیام واقعی را در میز آزمایش بفرستید و خروجی را با برچسب خودتان مقایسه کنید. هر جا ایجنت مطمئن نباشد answered را false میگذارد و handoff را true، تا پیام به آدم برسد؛ با «افزودن به دانستهها» تعریف برچسب را دقیقتر میکنید.
- میشود برچسب را مستقیم در دیتابیس ذخیره کرد؟
- بله. اگر بکاندتان روی فیکاروست، یک فانکشن پروژه ردیف را میسازد، با ctx.ai.ask از ایجنت دستهبند میپرسد و برچسب را کنار همان ردیف ذخیره میکند. کلید ایجنت و سرور جدا لازم نیست.
- خروجی همیشه JSON معتبر است؟
- بله. سرور هر خروجی را پیش از تحویل با شکلی که تعریف کردهاید میسنجد. جوابی که نخواند به کد شما نمیرسد و بهجایش خطای 502 با کد output_invalid برمیگردد.
- استخراج اطلاعات از متن، فیلدی را که در متن نیست حدس میزند؟
- در قالب استخراج فیلد نه: دستورالعمل میگوید فیلدی را که در متن نیامده null بگذار. مثلاً آگهی بدون قیمت، price برابر null برمیگرداند.
- میشود چند برچسب همزمان به یک پیام داد؟
- خروجی برچسبی دقیقاً یکی است. اگر چند بعد لازم دارید، مثلاً موضوع و فوریت، شکل شیء با دو فیلد متنی بسازید و برای هر کدام فهرست مقدار مجاز بگذارید.
مطالب مرتبط
- ۳ دقیقه مطالعه
خطای CORS در اتصال وباپ به API؛ ۴ علت و راهحل
خطای CORS یعنی مرورگر پاسخ را مسدود کرده، نه اینکه سرور خراب باشد. چهار علت رایج (credentials، هدر سفارشی، PUT، آدرس اشتباه) را با کد درست ببینید.
- ۱۰ دقیقه مطالعه
نوبت دهی با هوش مصنوعی؛ چت باتی که وقت خالی را رزرو میکند
منشی هوشمندی بسازید که از تقویم واقعی مطب یا سالن ساعت خالی را میگوید و با تأیید مراجع همانجا نوبت ثبت میکند؛ قالب رزرو، دو تابع و چک تداخل، با کد کامل.