API مهاجرت: رفع خطاهای رایج یکپارچه‌سازی LLM

پیکربندی نادرست Base URL

نقطه شکست اولیه تقریباً همیشه URL پایه است. هنگام تغییر ارائه‌دهندگان، باید انتهای نقطه (endpoint) که SDK شما به آن متصل می‌شود را به‌روزرسانی کنید. یک URL نادرست منجر به خطای 404 یا 403 می‌شود، حتی قبل از اینکه درخواست از ماشین شما خارج شود.

مشتری به دامنه صحیح اشاره می‌کند. برای سرویس ما، URL پایه https://api.apimigration.com/v1. این URL با SDKهای استاندارد OpenAI با تغییر ساده base_url پارامتر.

• پروتکل (HTTPS در مقابل HTTP) را بررسی کنید.
• بررسی اسلش‌های پایانی در پیکربندی کلاینت خود.
• تایید کنید که مسیر نسخه (/v1) با مشخصات API شما مطابقت دارد.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

نادیده گرفتن محدودیت‌های پنجره زمینه

مدل شما یک محدودیت سخت ۱۰۰,۰۰۰ توکنی برای مجموع prompt و completion دارد. اگر این را تجاوز کنید، API درخواست را رد می‌کند یا تاریخچه شما را بسته به پیاده‌سازی به صورت خاموش truncates می‌کند. همیشه مصرف توکن خود را ردیابی کنید تا از برخورد به این دیوار جلوگیری کنید.

علاوه بر این، حداکثر خروجی در هر درخواست ۱۶,۰۰۰ توکن است. اگر تنظیم نکنید max_tokens, پیش‌فرض ۲,۰۴۸ توکن است. این تفاوت برای وظایف تولید محتوای بلند قابل توجه است.

• مجموع کل توکن‌ها را به ازای هر درخواست پایش کنید.
• تنظیم max_tokens به طور صریح برای خروجی‌های طولانی.
• منطق پنجره لغزان را برای مکالمات بسیار طولانی پیاده‌سازی کنید.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

پیاده‌سازی نادرست پخش زنده

پاسخ‌های استریم‌شده نیاز به مدیریت خاص رویدادهای Server-Sent Events (SSE) دارند. اگر یک جریان را به عنوان یک شیء JSON واحد در نظر بگیرید، کد شما گیر می‌کند یا کرش می‌کند. هر قطعه حاوی داده‌های جزئی است و قطعه‌ی نهایی شامل آمار مصرف توکن است.

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

• اتصال را باز کنید و خط به خط بخوانید.
• تجزیه data: خط‌ها به عنوان JSON.
• مدیریت [DONE] به درستی سیگنال دهد.

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell the story in second person."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

نادیده گرفتن محدودیت‌های نرخ

API ما اجازه ۳۰۰ درخواست در دقیقه به ازای هر کلید را می‌دهد. اگر برنامه شما افزایش ناگهانی ترافیک داشته باشد، خطاهای 429 Too Many Requests دریافت خواهید کرد. باید برای مدیریت این خطاها به صورت منظم، از بازگشت نمایی (exponential backoff) استفاده کنید.

درخواست‌های موازی نیز برای هر کلید به 8 درخواست در یک زمان محدود می‌شوند. فراتر رفتن از این محدودیت می‌تواند باعث تخلیه مخزن اتصال شود. اتصالات همزمان خود را به دقت مانیتور کنید.

• برای خطاهای 429 از بازگشت نمایی استفاده کنید.
• محدودیت اتصالات همزمان به ۸.
• برای بارهای کاری بالا از الگوی Circuit Breaker استفاده کنید.

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apimigration.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

فرض بر فرمت‌های استاندارد JSON

اگرچه از قالب‌های سازگار با OpenAI پیروی می‌کنیم، اما فرضیات می‌توانند ادغام شما را مختل کنند. مطمئن شوید درخواست json_object در response_format اگر به JSON دقیق نیاز دارید. بدون این، مدل ممکن است مارک‌داون یا متن ساده را بازگرداند.

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

• تنظیم response_format به {"type": "json_object"}.
• JSON را قبل از پارس کردن اعتبارسنجی کنید.
• پاسخ‌های نادرست را به‌صورت ایمن مدیریت کنید.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

نادیده گرفتن مدیریت خطاها

APIها ممکن است شکست بخورند. زمان‌های انتظار شبکه، خطاهای سرور و پیکربندی‌های نامعتبر رخ می‌دهد. کد شما باید این خطاها را بدون کرش کردن مدیریت کند. جزئیات خطا را برای اشکال‌زدایی لاگ کنید.

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

• کدها و پیام‌های خطا را ثبت کنید.
• در صورت خطاهای 5xx با بازگشت نمایی تلاش مجدد انجام دهید.
• در خطاهای 4xx سریع شکست بخورید.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

مشکلات پرداخت و چرخش کلید

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

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

• موجودی اعتبار را به‌طور منظم پایش کنید.
• کلیدها را به صورت اتمی بچرخانید.
• همه نمونه‌ها را همزمان به‌روزرسانی کنید.

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apimigration.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

خلاصه بهترین شیوه‌ها

موفقیت مهاجرت به توجه به جزئیات بستگی دارد. URL پایه خود را بررسی کنید. محدودیت‌های context را رعایت کنید. استریم را به درستی مدیریت کنید. محدودیت نرخ را مدیریت کنید. JSON را اعتبارسنجی کنید. خطاها را مدیریت کنید. پرداخت‌ها و کلیدها را مدیریت کنید. دنبال کردن این مراحل یک انتقال روان را تضمین می‌کند.

یکپارچه‌سازی خود را پیش از انتشار عمومی به‌دقت آزمایش کنید. از اعتبار آزمایشی برای تأیید تنظیمات خود استفاده کنید. این کار از downtime پرهزینه در محیط تولید جلوگیری می‌کند.

• URL پایه را تأیید کنید.
• به محدودیت‌های زمینه احترام بگذارید.
• استریم را به درستی مدیریت کنید.
• محدودیت‌های نرخ.
• JSON را اعتبارسنجی کنید.
• خطاها را مدیریت کنید.
• مدیریت پرداخت‌ها و کلیدها.

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'