پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

مرجع API استخراج

API استخراج شواهد ارسالی را می‌خواند و مقدارهای نام‌دار و نوع‌دار برمی‌گرداند. با Clairic از Cloudflare، می‌توانید شناسه‌ای را عیناً از متن استخراج کنید، تاریخ یا مبلغی را محاسبه کنید، فهرستی بسازید، مقدار نامعلومی را برآورد کنید یا دنباله‌ای را پیش‌بینی کنید. هر نتیجه، نشانه‌های عدم قطعیت مدل را در صورت وجود حفظ می‌کند. برنامه شما باید پیش از ذخیره مقدارها یا انجام اقدام بر اساس آن‌ها، اعتبارشان را بررسی کند.

از cf.clairic در https://api.avalai.ir/v1/extraction استفاده کنید. قالب این نقطه پایانی با Decisions و SystemOne تفاوت دارد: استخراج از state و fields استفاده می‌کند، نه input، questions، choices یا criteria. مدل‌های تصمیم‌گیری Clef به آن دو نقطه پایانی تعلق دارند، نه این مسیر.

دامنه بررسی در ۱۴۰۵-۰۸-۰۲ (2026-10-24): این مرجع، قالب‌های رسمی فعلی Cloudflare را با فهرست مدل‌ها و کد فعلی نقطه پایانی AvalAI ترکیب می‌کند. درخواست‌ها و پاسخ‌های زیر مثال مستندات‌اند؛ هیچ پاسخ زنده‌ای از API استخراج AvalAI برای این صفحه ثبت نشده است. رفتار ورودی تصویری اختیاری، همه نوع‌های فیلد، درخواست‌های بزرگ و کیفیت پیش‌بینی را پیش از استفاده در برنامه، در مسیر انتخابی AvalAI بررسی کنید. راهنمای کاربردی مراحل بعدی را توضیح می‌دهد.

نقطه پایانی، احراز هویت و مدل

text

POST https://api.avalai.ir/v1/extraction

JSON با رمزگذاری UTF-8 و هدرهای Content-Type: application/json و Authorization: Bearer … بفرستید. کلید AvalAI را در سمت سرور از AVALAI_API_KEY بخوانید. فراخواننده به حساب یا کلید API جداگانه Cloudflare نیاز ندارد. احراز هویت را ببینید.

شناسه مدل AvalAI	دسته	حداقل سطح	ورودی / ورودی نهان‌شده / خروجی، دلار برای هر ۱ میلیون توکن
`cf.clairic`	استخراج	`0`	`$0.10 / $0.00 / $0.00`

فهرست فعلی AvalAI برای این مدل، ظرفیت ورودی 65,536 توکن و پشتیبانی از تصویر را ثبت می‌کند. Cloudflare مدل Clairic را پیش‌نمایش معرفی می‌کند. قالب این ارائه‌دهنده، جداگانه از تقسیم تعریف فیلدها میان نوبت‌های پردازش 8,192 توکنی سخن می‌گوید؛ این توضیح پردازش داخلی است و نباید آن را حد عمومی دیگری برای ورودی دانست. از ظرفیت درج‌شده در فهرست به‌تنهایی نتیجه نگیرید که چه مقدار متن طولانی حفظ می‌شود. truncated را بررسی کنید، شواهد را محدود نگه دارید و اندازه‌های موردنیاز برنامه را آزمایش کنید.

کد مسیر استخراج فقط cf.clairic را می‌پذیرد. cf.clef، cf.clef-flash و cf.clef-omni مدل‌های تصمیم‌گیری برای /v1/decisions و /v1/systemone هستند. این چهار مدل، مدل مکالمه برای /v1/chat/completions یا /v1/responses نیستند. صفحات Cloudflare، مدل‌ها و قیمت‌گذاری را ببینید.

بدنه درخواست

فیلد	نوع	الزام یا مقدار پیش‌فرض	معنا
`model`	رشته	الزامی	شناسه AvalAI یعنی `cf.clairic` را بفرستید. AvalAI مسیر بالادستی را انتخاب می‌کند؛ `clairic` یا `@cf/cloudflare/clairic` را در این فیلد جایگزین نکنید.
`state`	رشته	متن غیرخالی الزامی است، مگر اینکه `images` ارسال شود	شواهدی که باید خوانده شوند. این نقطه پایانی، شیء یا آرایه را به‌عنوان وضعیت بومی نمی‌پذیرد؛ رکوردهای مرتبط را به متن تبدیل کنید. قالب Cloudflare برای درخواست فقط تصویری، مقدار پیش‌فرض `""` را تعریف می‌کند.
`fields`	شیء، یا قالب کوتاه/فهرستی AvalAI	الزامی؛ دست‌کم یک فیلد	تعریف‌های نام‌دار و نوع‌دار که در ادامه توضیح داده می‌شوند. قالب کامل شیء را ترجیح دهید.
`images`	آرایه	اختیاری؛ حداکثر `4`	تصویرهای جاسازی‌شده؛ بخش ورودی تصویری را ببینید. URL راه دور پذیرفته نمی‌شود.
`reference_date`	رشته	اختیاری؛ مقدار پیش‌فرض مشخص نشده	تاریخ ISO که تاریخ‌های بدون سال را تفسیر می‌کند، مانند `2026-09-02`. هنگامی که این ابهام مهم است، آن را بفرستید.
`options`	شیء	اختیاری	گزینه‌های `include_quantiles` و `return_state_text` که در ادامه آمده‌اند.

پاسخ جریانی پشتیبانی نمی‌شود. stream: true نفرستید. مسیر، state، fields، images، reference_date و options را به ارائه‌دهنده می‌فرستد؛ تنظیمات دیگر ارائه‌دهنده، راه پشتیبانی‌شده‌ای برای کنترل استنتاج نیستند. فیلدهای سطح اول که حذف شده‌اند یا مقدار null دارند، به بالادست ارسال نمی‌شوند. تعریف فیلد با مقدار null نامعتبر است؛ چنین تعریفی درخواست پاسخ ناموجود نیست.

نام فیلد و قالب‌های تعریف

نام فیلد بین ۱ تا ۶۴ نویسه دارد، با حرف ASCII یا _ شروع می‌شود و پس از آن فقط حرف ASCII، رقم، _، . یا - می‌پذیرد. الگوی دقیق آن ^[A-Za-z_][A-Za-z0-9_.\-]{0,63}$ است. قالب Cloudflare حد بالایی برای تعداد فیلدها تعیین نمی‌کند، اما تعریف‌های بزرگ همچنان توکن ورودی مصرف می‌کنند و ممکن است به چند نوبت پردازش نیاز داشته باشند. نام‌های متمایز انتخاب کنید؛ در قالب فهرستی، مقدارهای name را تکرار نکنید، زیرا تبدیل به شیء نمی‌تواند کلیدهای تکراری را حفظ کند.

سه تعریف زیر در AvalAI یک فیلد یکسان را بیان می‌کنند:

json

{
  "fields": {
    "invoice_number": {
      "type": "text"
    }
  }
}

json

{
  "fields": {
    "invoice_number": "text"
  }
}

json

{
  "fields": [
    {
      "name": "invoice_number",
      "type": "text"
    }
  ]
}

AvalAI تعریف کوتاه و ورودی‌های فهرستی را به قالب شیء Cloudflare با کلید نام فیلد تبدیل می‌کند. قالب کامل شیء، تنظیمات تو‌در‌تو را آشکار می‌کند و وابستگی به این تبدیل کمکی را کاهش می‌دهد.

هر نه نوع فیلد

در هر تعریف کامل، type الزامی است. instructions متن اختیاری برای توصیف مقدار موردنظر است. هنگامی که نام به‌تنهایی مبهم است، منبع، نقش و محاسبه موردنظر را روشن کنید.

`type`	کاربرد	تنظیمات و تفسیر
`text`	استخراج رشته از شواهد	پاسخ بر اساس متن می‌تواند موقعیت‌های `span` و یک `guess` عین متن داشته باشد. پیش از پذیرش آن حدس، `value` را بررسی کنید.
`number`	استخراج یا محاسبه مقدار عددی	گزینه‌های اختیاری `unit`، `integer` و `decimals`. متناهی‌بودن، محدوده، ارز و محاسبه دقیق را در کد بررسی کنید.
`date`	استخراج یا محاسبه تاریخ تقویمی	`reference_date` مرجع تاریخ بدون سال است. مثال Cloudflare رشته تاریخ ISO برمی‌گرداند؛ معتبر بودن تاریخ را بررسی کنید.
`time`	درخواست مقدار زمان	نوعی پشتیبانی‌شده در قالب است. قالب خروجی منتشرشده، شکل رشته زمان یا قاعده منطقه زمانی را تعیین نمی‌کند؛ نمایش موردنیاز خود را اعتبارسنجی کنید.
`datetime`	درخواست تاریخ و زمان ترکیبی	نوعی پشتیبانی‌شده است. قالب خروجی، منطقه زمانی، اختلاف زمانی یا رفع ابهام را مشخص نمی‌کند؛ این قواعد را برای برنامه تعریف و بررسی کنید.
`duration`	درخواست مقدار زمان سپری‌شده	گزینه‌های اختیاری `unit`، `integer` و `decimals`. مدت را از زمان وقوع جدا نگه دارید؛ ماه و سال تقویمی به سیاست صریح برنامه نیاز دارند.
`list`	بازگرداندن چند مقدار	`items: "text"`، `"number"` یا `"date"` الزامی است. فهرست عددی می‌تواند `decimals` داشته باشد. فهرست متنی می‌تواند `spans` هر عضو را برگرداند. هر عضو را بررسی کنید.
`estimate`	پیش‌بینی مقدار نامطمئن در شبکه مقدارها	`min` و `max` الزامی‌اند؛ `step` و `scale` اختیاری‌اند. خلاصه توزیع و احتمال بیرون محدوده را بخوانید؛ برآورد را واقعیت مشاهده‌شده ندانید.
`forecast`	پیش‌بینی چند گام آینده	محدوده و شبکه برآورد را همراه با `horizon` و `interval` به کار می‌برد. نتیجه می‌تواند `steps` داشته باشد؛ هر گام را بررسی کنید و مبنای زمانی انتخابی برنامه را حفظ کنید.

تنظیمات تو‌در‌توی فیلد

قالب ورودی رسمی، ویژگی‌های زیر را تعریف می‌کند. AvalAI نام و نوع پایه فیلد را محلی بررسی می‌کند و اعتبارسنجی تنظیمات خاص ارائه‌دهنده را به بالادست می‌سپارد؛ عبور از بررسی محلی، معتبر بودن ترکیب دلخواه تنظیمات را ثابت نمی‌کند.

تنظیم	قالب و مقدار پیش‌فرض	کاربرد و معنا
`instructions`	رشته؛ مقدار پیش‌فرض مشخص نشده	توصیف مقداری که باید استخراج، محاسبه یا پیش‌بینی شود.
`unit`	رشته	برچسب واحد کمیت. برای `duration` از `seconds`، `minutes`، `hours`، `days`، `weeks`، `months` یا `years` استفاده کنید؛ پیش‌فرض `seconds` است.
`integer`	بولی؛ مقدار پیش‌فرض مشخص نشده	برای `number` و `duration`.
`decimals`	عدد صحیح `0–6`؛ مقدار پیش‌فرض مشخص نشده	برای `number`، `duration` و فهرست عددی. دقت درخواستی، درستی گرد کردن یا دقت منبع را ثابت نمی‌کند.
`items`	`text`، `number` یا `date`؛ برای فهرست الزامی	نوع هر عضو فهرست؛ شیء دلخواه JSON تو‌در‌تو، نوع مستندشده عضو فهرست نیست.
`min`، `max`	برای `estimate` و `forecast` الزامی	عدد، یا تاریخ ISO برای برآورد تاریخ. محدوده، شبکه پیش‌بینی را توصیف می‌کند و نتیجه را تضمین نمی‌کند.
`step`	عدد مثبت، یا `month` / `year`؛ مقدار پیش‌فرض مشخص نشده	فاصله نقاط شبکه عددی؛ در برآورد تاریخ، گام عددی بر حسب روز است.
`scale`	`linear` یا `log`؛ پیش‌فرض `linear`	مقیاس شبکه برآورد. بررسی محدوده لازم برای شبکه لگاریتمی را به بالادست بسپارید.
`null_threshold`	عدد بزرگ‌تر از `0` و حداکثر `1`؛ پیش‌فرض `0.5`	آستانه احتمال ناموجود بودن پاسخ که بالاتر از آن، `value` برابر `null` می‌شود. کاهش آن، رفتار خودداری از پاسخ را تغییر می‌دهد؛ به‌خودی‌خود دقت بهتر را ثابت نمی‌کند.
`horizon`	عدد صحیح `1–64`؛ مقدار پیش‌فرض مشخص نشده	تعداد گام پیش‌بینی. برای پیش‌بینی آن را بفرستید و مقدار حذف‌شده را حدس نزنید.
`interval`	`step`، `minute`، `hour`، `day`، `week`، `month`، `quarter` یا `year`؛ مقدار پیش‌فرض مشخص نشده	فاصله زمانی پیش‌بینی. آن را بفرستید و زمان مرجع را در برنامه حفظ کنید.

برای نمونه، موارد زیر تعریف فیلد هستند، نه درخواست کامل یا خروجی ثبت‌شده:

json

{
  "meeting_time": {
    "type": "time",
    "instructions": "Start time explicitly stated in the note"
  },
  "appointment": {
    "type": "datetime",
    "instructions": "Appointment date and time explicitly stated in the note"
  },
  "elapsed": {
    "type": "duration",
    "unit": "minutes",
    "integer": true
  },
  "quantities": {
    "type": "list",
    "items": "number",
    "decimals": 2
  },
  "arrival": {
    "type": "estimate",
    "min": "2026-10-01",
    "max": "2026-10-31",
    "step": 1
  },
  "daily_demand": {
    "type": "forecast",
    "min": 0,
    "max": 100,
    "step": 1,
    "horizon": 3,
    "interval": "day"
  }
}

گزینه‌ها

ویژگی درون `options`	نوع / پیش‌فرض	اثر
`include_quantiles`	بولی / `false`	از طریق `quantiles`، `99` صدک به برآورد اضافه می‌کند. قالب خروجی، شکل دقیق عضوها را تعریف نمی‌کند؛ داده بازگشتی را بررسی کنید.
`return_state_text`	بولی / `false`	`state_text` را برمی‌گرداند؛ متنی که موقعیت‌های پاسخ به آن اشاره می‌کنند. برای بررسی بخش منبع مفید است.

گزینه‌های غیرضروری را حذف کنید. قالب عمومی برای این نقطه پایانی، کنترل‌های تولید متن مانند دما، JSON Schema دلخواه یا فراخوانی ابزار تعریف نمی‌کند.

ورودی تصویری

Cloudflare تصویر جاسازی‌شده PNG، JPEG یا WebP را مستند می‌کند: حداکثر 4 تصویر، 4 MiB برای هر تصویر، مجموع 8 MiB بایت تصویر پس از رمزگشایی و 16 MiB برای کل بدنه درخواست. این‌ها محدودیت بالادستی هستند، نه محدودیت‌هایی که به‌صورت زنده در واسط AvalAI آزمایش شده باشند. رمزگذاری، اندازه درخواست را افزایش می‌دهد؛ حد بایت رمزگشایی‌شده با حد کل بدنه متفاوت است. کد AvalAI تعداد و شکل پایه تصویر جاسازی‌شده را بررسی می‌کند؛ بالادست، محتوای واقعی تصویر و محدودیت‌های تصویری دیگر را می‌سنجد.

از URL با پیشوند حروف کوچک data: یا شیئی دارای هر دو content_type و base64 استفاده کنید. بررسی محلی فعلی AvalAI، پیشوند حروف کوچک را لازم می‌داند، هرچند قالب خام Cloudflare حالت‌های دیگر حروف را هم می‌پذیرد. درخواست فقط تصویری می‌تواند state را حذف کند یا "" بفرستد؛ وضعیت فقط متنی باید نویسه‌ای غیر از فاصله داشته باشد. این مسیر، ورودی صوت، ویدئو، URL تصویر راه دور، بارگذاری PDF یا file_id را مستند نمی‌کند.

json

{
  "images": [
    {
      "content_type": "image/png",
      "base64": "<BASE64_ENCODED_IMAGE_BYTES>"
    }
  ]
}

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

درخواست کامل صورتحساب

سه کلاینت، همان بدنه شش‌فیلدی را می‌فرستند. Python فقط از کتابخانه استاندارد استفاده می‌کند؛ JavaScript به Node.js نسخه 18 یا بالاتر در سمت سرور نیاز دارد. هر کلاینت یک تلاش با مهلت محدود انجام می‌دهد و تکرار خودکار ندارد. هنگام بررسی سازگاری، داده آزمایشی ساختگی بفرستید. بخش Python یا JavaScript را در فایل ذخیره و با AVALAI_API_KEY که از قبل در محیط وجود دارد اجرا کنید.

BashPythonJavaScript

bash

curl --fail-with-body \
  --connect-timeout 10 --max-time 120 \
  https://api.avalai.ir/v1/extraction \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "model": "cf.clairic",
    "state": "Invoice INV-2291 from Northwind Supply, issued 2026-09-02, net 30. 4 pallets at $250.00 each, shipping $80.00. Contact: Dana Ruiz, Priya Shah.",
    "fields": {
      "invoice_number": {"type": "text"},
      "due_date": {"type": "date", "instructions": "Issue date plus the net payment days"},
      "total": {"type": "number", "decimals": 2, "unit": "USD", "instructions": "Amount due including shipping"},
      "contacts": {"type": "list", "items": "text"},
      "po_number": {"type": "text", "instructions": "Purchase order number"},
      "days_to_pay": {"type": "estimate", "min": 0, "max": 120, "step": 1, "instructions": "Days after issue until this invoice is paid"}
    }
  }'

python

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

payload = {
    "model": "cf.clairic",
    "state": "Invoice INV-2291 from Northwind Supply, issued 2026-09-02, net 30. 4 pallets at $250.00 each, shipping $80.00. Contact: Dana Ruiz, Priya Shah.",
    "fields": {
        "invoice_number": {"type": "text"},
        "due_date": {
            "type": "date",
            "instructions": "Issue date plus the net payment days",
        },
        "total": {
            "type": "number",
            "decimals": 2,
            "unit": "USD",
            "instructions": "Amount due including shipping",
        },
        "contacts": {"type": "list", "items": "text"},
        "po_number": {"type": "text", "instructions": "Purchase order number"},
        "days_to_pay": {
            "type": "estimate",
            "min": 0,
            "max": 120,
            "step": 1,
            "instructions": "Days after issue until this invoice is paid",
        },
    },
}
request = Request(
    "https://api.avalai.ir/v1/extraction",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['AVALAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request, timeout=120) as response:
        result = json.load(response)
        print("avalai-request-id:", response.headers.get("avalai-request-id"))
except HTTPError as error:
    print("avalai-request-id:", error.headers.get("avalai-request-id"))
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise
print(json.dumps(result, indent=2, ensure_ascii=False))

javascript

const apiKey = process.env.AVALAI_API_KEY;
if (!apiKey) throw new Error("AVALAI_API_KEY is required");

const payload = {
  model: "cf.clairic",
  state: "Invoice INV-2291 from Northwind Supply, issued 2026-09-02, net 30. 4 pallets at $250.00 each, shipping $80.00. Contact: Dana Ruiz, Priya Shah.",
  fields: {
    invoice_number: { type: "text" },
    due_date: { type: "date", instructions: "Issue date plus the net payment days" },
    total: { type: "number", decimals: 2, unit: "USD", instructions: "Amount due including shipping" },
    contacts: { type: "list", items: "text" },
    po_number: { type: "text", instructions: "Purchase order number" },
    days_to_pay: { type: "estimate", min: 0, max: 120, step: 1, instructions: "Days after issue until this invoice is paid" },
  },
};
const response = await fetch("https://api.avalai.ir/v1/extraction", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
  signal: AbortSignal.timeout(120_000),
});
const text = await response.text();
console.log("avalai-request-id:", response.headers.get("avalai-request-id"));
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
console.log(JSON.stringify(JSON.parse(text), null, 2));

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

پاسخ موفق

کد فعلی، شیء result در پاسخ Cloudflare را جدا می‌کند، شناسه عمومی مدل را cf.clairic قرار می‌دهد و در صورت وجود برآورد هزینه، estimated_cost مربوط به AvalAI را اضافه می‌کند. پوشش success / errors مربوط به Cloudflare، قالب پاسخ موفق این مسیر نیست.

فیلد	نوع	معنا
`model`	رشته	شناسه مدل AvalAI؛ بازگرداندن همان شناسه، نسخه دقیق مدل زیرین را آشکار نمی‌کند.
`answers`	شیء	در قرارداد بالادستی، یک پاسخ نام‌دار برای هر فیلد درخواستی. هر پاسخ، `type` و `value` الزامی دارد.
`truncated`	بولی	آیا شواهد کوتاه شده‌اند. اگر متن حذف‌شده می‌تواند پاسخ را تغییر دهد، کوتاه شدن را مهم بدانید.
`state_text`	رشته، اختیاری	متن مرجع موقعیت‌ها، هنگامی که `return_state_text` فعال باشد.
`usage`	شیء	`input_tokens` و `output_tokens` الزامی؛ `state_tokens`، `image_tokens`، `schema_tokens` و `passes` اختیاری‌اند.
`estimated_cost`	شیء، اختیاری	برآورد دلاری و پول محلی AvalAI که در ادامه توضیح داده می‌شود.

پاسخ کامل برای توضیح قالب که از مثال صورتحساب Cloudflare و پوشش پاسخ در کد AvalAI اقتباس شده است. این پاسخ، ثبت زنده AvalAI نیست. مقدارهای عددی، مصرف، تعداد نوبت پردازش و حضور ویژگی‌های اختیاری ممکن است متفاوت باشند. irt و exchange_rate عمداً null هستند، زیرا این مثال هیچ نرخ تبدیل فعلی را تأیید نمی‌کند:

json

{
  "model": "cf.clairic",
  "answers": {
    "invoice_number": {
      "type": "text",
      "p_null": 3.8e-10,
      "span": [
        8,
        16
      ],
      "guess": "INV-2291",
      "confidence": 1,
      "value": "INV-2291"
    },
    "due_date": {
      "type": "date",
      "p_null": 1.9e-08,
      "guess": "2026-10-02",
      "confidence": 0.9999,
      "value": "2026-10-02"
    },
    "total": {
      "type": "number",
      "p_null": 2.3e-08,
      "guess": 1080,
      "confidence": 0.9999,
      "value": 1080
    },
    "contacts": {
      "type": "list",
      "value": [
        "Dana Ruiz",
        "Priya Shah"
      ],
      "spans": [
        [
          120,
          129
        ],
        [
          131,
          141
        ]
      ],
      "confidence": 0.9999
    },
    "po_number": {
      "type": "text",
      "p_null": 1,
      "span": [
        8,
        16
      ],
      "guess": "INV-2291",
      "confidence": 0.9995,
      "value": null
    },
    "days_to_pay": {
      "type": "estimate",
      "value": 30,
      "mean": 29.535,
      "median": 30,
      "p10": 21,
      "p90": 38,
      "p_below": 5.9e-06,
      "p_above": 1.2e-05
    }
  },
  "truncated": false,
  "usage": {
    "state_tokens": 61,
    "image_tokens": 0,
    "schema_tokens": 472,
    "input_tokens": 655,
    "output_tokens": 0,
    "passes": 3
  },
  "estimated_cost": {
    "unit": "0.0000655000",
    "irt": null,
    "exchange_rate": null
  }
}

مقدارها، عدم قطعیت و موقعیت متن

ابتدا value را بخوانید. value: null یعنی مدل مقدار پذیرفته‌شده‌ای به دست نیاورده است. guess ممکن است همچنان یک نامزد همراه با موقعیت متن و confidence بالا داشته باشد؛ این ویژگی‌ها، مقدار null را تغییر نمی‌دهند. مثال سفارش خرید ناموجود، عمداً شماره صورتحساب را حدس می‌زند، اما value: null و p_null: 1 برمی‌گرداند. ذخیره guess به‌عنوان شماره سفارش خرید، رکورد نادرست ایجاد می‌کند.

p_null برآورد می‌کند که آیا شواهد از هیچ پاسخی پشتیبانی نمی‌کنند؛ null_threshold تصمیم ارائه‌دهنده برای مقدار null را کنترل می‌کند. confidence نشانه بازگشتی جداگانه‌ای است. قالب عمومی خروجی، رابطه ریاضی میان این دو یا کالیبراسیون برنامه را تعریف نمی‌کند. آن‌ها را در هم ضرب نکنید، null را با حدس جایگزین نکنید و نبود ویژگی اطمینان را صفر ندانید. فهرست و برآورد لزوماً فراداده یکسانی با فیلد متنی ندارند.

span آرایه‌ای از موقعیت‌های عدد صحیح است؛ فهرست متنی ممکن است spans داشته باشد. مثال Cloudflare با موقعیت شروع و پایان، زیررشته را مشخص می‌کند. متن مرجع دقیق را حفظ کنید و پیش از استفاده از موقعیت‌ها به‌عنوان شاهد منبع، محدوده و زیررشته را بررسی کنید. شیوه شمارش نویسه Unicode ممکن است میان Python و JavaScript متفاوت باشد؛ قرارداد ارائه‌دهنده را با ورودی غیر ASCII بررسی کنید و موقعیت‌ها را بایت فرض نکنید. تاریخ و عدد محاسبه‌شده یا پیش‌بینی ممکن است بخش عیناً موجود در متن نداشته باشد.

برآورد و پیش‌بینی دنباله

برآورد می‌تواند value، mean، median، p10، p90، p_below، p_above و quantiles اختیاری برگرداند. مثال رسمی، محدوده p10 تا p90 را بازه 80% توصیف می‌کند. p_below و p_above احتمال بیرون شبکه درخواستی را حفظ می‌کنند. محدوده، قرار گرفتن نتیجه واقعی درون آن را تضمین نمی‌کند و باریک بودن بازه، دقت را نشان نمی‌دهد.

پیش‌بینی دنباله می‌تواند steps برگرداند که به‌صورت یک برآورد برای هر گام توصیف شده است. قالب عمومی خروجی، ساختار کامل تو‌در‌توی هر گام یا قالب value سطح اول پیش‌بینی را تعیین نمی‌کند. ساختار بازگشتی را حفظ کنید، با نمایش انتخابی برنامه اعتبارسنجی کنید و زمان مرجع و فاصله زمانی درخواست را به آن پیوند دهید. پیش‌بینی باید با مشاهده‌های بعدی سنجیده شود؛ فهرستی از واقعیت‌های استخراج‌شده نیست.

مصرف و هزینه

کد فعلی AvalAI برای cf.clairic، هزینه را بر اساس input_tokens گزارش‌شده × USD 0.10 / 1,000,000 محاسبه می‌کند. قیمت خروجی صفر است. ورودی ممکن است تعریف فیلدها، تصویر و نوبت‌های تکراری پردازش را در بر بگیرد؛ هزینه را فقط از طول متن وضعیت تخمین نزنید و برابری همیشگی state_tokens + image_tokens + schema_tokens با input_tokens قابل‌صورتحساب را فرض نکنید.

در مثال، 655 × 0.10 / 1,000,000 = USD 0.0000655 است که با estimated_cost.unit مطابقت دارد. unit مبلغ دلاری به‌صورت رشته اعشاری، irt برآورد تومان و exchange_rate نرخ تبدیل همان پاسخ است. دو مقدار آخر ممکن است null باشند؛ نرخ ثابتی جایگزین نکنید. نبود estimated_cost، رایگان بودن درخواست را ثابت نمی‌کند. راهنمای پیگیری هزینه تفاوت برآورد پاسخ با حسابداری تراکنش را توضیح می‌دهد.

قیمت صفر ورودی نهان‌شده در فهرست، کنترل حافظه نهان، رخداد استفاده از آن یا طول عمرش را برای استخراج ثابت نمی‌کند. passes تعداد نوبت‌های پردازش است، نه شمار تلاش مجدد درخواست. مصرف هر پاسخ را حفظ کنید؛ تکرار استنتاج می‌تواند هزینه ورودی دیگری داشته باشد.

خطاها و تلاش مجدد

خطاهای اعتبارسنجی استخراج و شکست بالادستی در شیء error قرار می‌گیرند. بررسی محلی می‌تواند param را مشخص کند؛ خطای بالادستی ممکن است آن را نداشته باشد. پاسخ زیر، نمونه توضیحی بررسی محلی برای stream: true است، نه پاسخ ثبت‌شده زنده:

json

{
  "error": {
    "message": "Streaming is not supported on /v1/extraction.",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": "stream",
    "request_id": "<AVALAI_REQUEST_ID>"
  }
}

وضعیت / نشانه	قرارداد فعلی و اقدام مناسب
`400`	مدل نامناسب، پاسخ جریانی، فیلد خالی یا نامعتبر، وضعیت نامعتبر یا شکل نادرست تصویر جاسازی‌شده در بررسی محلی؛ بعضی خطاهای قالب بالادستی هم `400` هستند. پیش از تکرار، درخواست را اصلاح کنید.
`401` / `403` هنگام پذیرش درخواست در AvalAI	احراز هویت، مجوز و سطح AvalAI را بررسی کنید. خطای کلید ارائه‌دهنده، جداگانه به `503` تبدیل می‌شود؛ به معنی درخواست کلید Cloudflare از فراخواننده نیست.
`413`	درخواست بیش‌ازحد بزرگ در بالادست، در صورت وجود جزئیات اعتبارسنجی، می‌تواند همین وضعیت را حفظ کند. بدنه را کوچک کنید؛ بایت‌های بدون تغییر را دوباره نفرستید.
`422`	تنظیمات خاص ارائه‌دهنده، مانند محدوده برآورد، ممکن است در بالادست نامعتبر باشند. پیام پاک‌سازی‌شده را بررسی و تعریف فیلد را اصلاح کنید.
`429`	محدودیت نرخ ارائه‌دهنده به `rate_limit_exceeded` نگاشت می‌شود؛ AvalAI نیز ممکن است هنگام پذیرش درخواست، نرخ یا سهمیه را محدود کند. پیش از تکرار، بدنه را بررسی کنید.
`503`	خطای ارتباط یا پایان مهلت ارائه‌دهنده، خطای احراز هویت ارائه‌دهنده، نبود دسترسی به ارائه‌دهنده، نتیجه غیر JSON یا نتیجه بدون `answers`. برای خطای موقت، تلاش مجدد محدود ممکن است مناسب باشد.

کد، پیام‌های اعتبارسنجی بالادستی را پاک‌سازی می‌کند و شکست کلید یا سرور ارائه‌دهنده را با پیام عمومی نبود دسترسی جایگزین می‌کند. وضعیت HTTP، شناسه مدل، بدنه خطای بدون اطلاعات حساس و هدر پاسخ avalai-request-id را در صورت وجود حفظ کنید. هدرهای پاسخ و مدیریت خطا را ببینید.

برای تلاش مجدد برنامه، سقف تعداد کل تلاش‌ها و مهلت کل تعیین کنید، فاصله افزایشی محدود به کار ببرید و تأخیر بازگشتی سرور را در صورت وجود رعایت کنید. برای quota_exceeded یا insufficient_quota، درخواست نامعتبر، JSON نامعتبر پاسخ موفق یا قالب پاسخ ناسازگار توقف کنید. پایان مهلت ممکن است پس از پردازش و محاسبه هزینه رخ دهد؛ این مرجع قراردادی برای کلید جلوگیری از تکرار استخراج تأیید نمی‌کند. نوشتن در پایگاه داده، اعلان و پرداخت را خارج از حلقه تلاش مجدد استنتاج نگه دارید.

منابع و گام بعدی

مرجع رسمی مدل Clairic در Cloudflare: وضعیت پیش‌نمایش، مثال صورتحساب، تصویر و توضیح پردازش.
قالب رسمی ورودی Clairic: نوع‌های فیلد، تنظیمات تو‌در‌تو، گزینه‌ها و محدودیت‌ها.
قالب رسمی خروجی Clairic: پوشش پاسخ و فراداده اختیاری هر جواب.
راهنمای مدل‌های استخراج: گردش کار کامل اعتبارسنجی صورتحساب و بازبینی.
Decisions و SystemOne: داوری محدود با مدل‌های Clef و Jev.

مرجع API استخراج ​

نقطه پایانی، احراز هویت و مدل ​

بدنه درخواست ​

نام فیلد و قالب‌های تعریف ​

هر نه نوع فیلد ​

تنظیمات تو‌در‌توی فیلد ​

گزینه‌ها ​

ورودی تصویری ​

درخواست کامل صورتحساب ​

پاسخ موفق ​

مقدارها، عدم قطعیت و موقعیت متن ​

برآورد و پیش‌بینی دنباله ​

مصرف و هزینه ​

خطاها و تلاش مجدد ​

منابع و گام بعدی ​

مرجع API استخراج

نقطه پایانی، احراز هویت و مدل

بدنه درخواست

نام فیلد و قالب‌های تعریف

هر نه نوع فیلد

تنظیمات تو‌در‌توی فیلد

گزینه‌ها

ورودی تصویری

درخواست کامل صورتحساب

پاسخ موفق

مقدارها، عدم قطعیت و موقعیت متن

برآورد و پیش‌بینی دنباله

مصرف و هزینه

خطاها و تلاش مجدد

منابع و گام بعدی