سازگاری با OpenAI و مهاجرت از OpenAI، Azure و دیگران

یوتاپن همان قرارداد chat/completions را پیاده کرده که SDK رسمی OpenAI با آن حرف می‌زند. اگر کدت الان با OpenAI، Azure OpenAI یا هر سرویس سازگار دیگری کار می‌کند، مهاجرت یعنی دو تغییر: آدرس پایه و کلید. شناسهٔ مدل هم شکل provider/model می‌گیرد. باقی صفحه دربارهٔ همین جزئیات و چند تفاوت کوچک است.

تغییر base_url

# قبل
client = OpenAI(api_key="sk-...")

# بعد
client = OpenAI(
    base_url="https://api.uttapen.ir/v1",
    api_key="sk-up-...",
)

در Node نام فیلد baseURL است؛ در PHP withBaseUri()؛ در Go option.WithBaseURL(). اگر SDK از متغیر محیطی می‌خواند، OPENAI_BASE_URL=https://api.uttapen.ir/v1 و OPENAI_API_KEY=sk-up-... را ست کن و کد را دست نزن. مسیر /v1 جزء آدرس است؛ بدون آن 404 می‌گیری.

شناسهٔ مدل

شناسه‌ها به شکل سازنده/مدل هستند، چون کاتالوگ ما مدل‌های چند سازنده را کنار هم دارد و اسم خالی مدل بین آن‌ها یکتا نیست:

فهرست کامل با قیمت تومانی در صفحهٔ مدل‌ها یا GET /v1/models (بدون کلید هم کار می‌کند). پسوندهای :free، :batch و :online هم پشتیبانی می‌شوند. شناسهٔ بدون نام سازنده (gpt-5) پذیرفته نمی‌شود و 404 model_not_found برمی‌گرداند.

چه چیزهایی پشتیبانی می‌شود

Responses API بعد از تثبیت شکل رویدادهایش برای متر کردن هزینه اضافه می‌شود. تا آن روز، هر چیزی که در Responses می‌خواهی (tools، تصویر، JSON، reasoning) در chat/completions هم هست؛ فقط شکل بدنه فرق دارد.

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

بدنهٔ درخواست تو تقریباً دست‌نخورده به مدل می‌رسد. چند فیلد اضافه فراتر از قرارداد OpenAI هم پشتیبانی می‌شود:

• provider — ترجیح یا اجبار یک ارائه‌دهندهٔ خاص برای یک مدل (مثلاً {"order": ["Anthropic"], "allow_fallbacks": false} در بدنه). برای کاربر حرفه‌ای که به latency یا region حساس است.
• models — فهرست مدل‌های جایگزین. اگر مدل اول جواب نداد، بعدی امتحان می‌شود. رزرو هزینه با گران‌ترین مدل فهرست محاسبه می‌شود، ولی شارژ نهایی با مدلی است که واقعاً پاسخ داده.
• reasoning، plugins، web_search_options، transforms — عبور می‌کنند و در برآورد هزینه لحاظ می‌شوند.

دو فیلد را خودمان اضافه می‌کنیم: usage: {include: true} تا مصرف واقعی برگردد، و stream: true به سمت مدل حتی وقتی تو استریم نخواسته‌ای. در حالت دوم یوتاپن تکه‌های استریم را جمع می‌کند و یک JSON استاندارد تحویلت می‌دهد، پس از بیرون فرقی نمی‌بینی.

تفاوت‌های رفتاری

• فیلدهای عددی باید عدد صحیح JSON باشند. max_tokens، max_completion_tokens، max_output_tokens، n و best_of به‌صورت "100" (رشته)، 100.0 یا 1e2 رد می‌شوند و 400 invalid_request می‌گیری. دلیلش این است که برآورد هزینه نباید با نمایشی که مدل می‌پذیرد ولی ما نمی‌خوانیم دور زده شود.
• 402 قبل از ارسال. اگر موجودی قابل‌استفاده از برآورد هزینهٔ درخواست کمتر باشد، درخواست اصلاً به مدل نمی‌رود. max_tokens کوچک‌تر یعنی رزرو کوچک‌تر (قیمت‌گذاری).
• حداکثر بدنه ۲۰ مگابایت است؛ بیشتر از آن 413.
• پیام‌های خطای مدل عیناً با همان status برمی‌گردند، فقط رشته‌های داخلی زیرساخت از متن پاک شده‌اند.
• بدون ذخیرهٔ محتوا. پرامپت و پاسخ در مسیر API جایی ثبت نمی‌شوند (حریم خصوصی).
• تأخیر اضافه نسبت به فراخوانی مستقیم مدل حدود ۱۰۰ میلی‌ثانیه است.

اشتباه‌های رایج

مهاجرت از یک سرویس سازگار دیگر

اگر تا حالا از یک سرویس واسط دیگر با API سازگار OpenAI استفاده می‌کردی، فقط آدرس پایه و کلید عوض می‌شود و شکل شناسهٔ مدل همان سازنده/مدل می‌ماند. تفاوت‌های عملی: تسویه به تومان از کیف پول یوتاپن است، هزینهٔ هر درخواست در هدر پاسخ می‌آید، و هیچ درخواستی از IP ایران به سرویس‌های خارجی نمی‌رسد.

مهاجرت از Azure OpenAI

کلاینت AzureOpenAI را با OpenAI معمولی جایگزین کن؛ api_version و azure_endpoint معنایی ندارند و نام deployment جای خودش را به شناسهٔ provider/model می‌دهد.