سادگیِ انتقال در برابر فقدان کنترل؛ بهای استفاده از SDK مشترک

تصور کنید برنامه‌نویسی هستید که می‌خواهد بدون تغییر دادن هزاران خط کد، مدل Sonnet 4.6 را جایگزین GPT-4 کند و این کار را تنها با تغییر یک آدرس URL انجام دهد. این سناریو دیگر یک رویای مهندسی نیست، بلکه واقعیتِ جدیدِ تعامل با مدل‌های زبانی است. در این حالت، SDK (کیت توسعه نرم‌افزار) دیگر نماینده‌ی یک مدل خاص نیست، بلکه صرفاً کلاینتی است که یک پروتکل شبکه مشخص را صحبت می‌کند.

برای درک بهتر، این قطعه کد را در نظر بگیرید: شما بسته OpenAI را نصب می‌کنید، کلاس OpenAI را وارد می‌کنید و متد client.chat.completions.create() را فرا می‌خوانید. با این حال، کسی که پاسخ می‌دهد Claude است.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://api.anthropic.com/v1/",
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "user", "content": "Explain this in one sentence."}
    ],
)
print(response.choices[0].message.content)

با تنظیم api_key روی یک کلید مربوط به Anthropic و تغییر base_url به https://api.anthropic.com/v1/، SDK شرکت OpenAI دستورات را به سبک HTTP-OpenAI ارسال می‌کند. در طرف مقابل، نقطه اتصال (Endpoint) سازگاری Anthropic این درخواست را دریافت کرده، آن را به فرمتی که Claude Sonnet بفهمد ترجمه می‌کند و سپس نتیجه را دوباره به شکل یک پاسخ OpenAI بازمی‌گرداند تا SDK بتواند آن را از طریق مسیر response.choices[0].message.content تجزیه و نمایش دهد.

همان‌طور که در تحلیل‌های قبلی ما درباره‌ی پایداری زیرساخت‌های هوش مصنوعی و خطرات رخنه‌های محیط Sandbox اشاره کردیم، این حرکت نشان‌دهنده‌ی گذار صنعت به سمت پشته‌های «مدل-ناپذیر» (Model Agnostic) است؛ جایی که توسعه‌دهندگان می‌خواهند از وابستگی به یک شرکت خاص (Vendor Lock-in) خلاص شوند. این رویکرد با استراتژی‌های جداسازی چت‌بات‌ها از SDKهای اختصاصی هم‌راستا است تا انعطاف‌پذیری سیستم افزایش یابد. اما این راحتی، بهایی دارد: تقابل میان جابه‌جایی سریع و بهره‌برداری کامل از قابلیت‌های مدل. در پشته‌های مدرن AI، انتخاب کتابخانه توسط برنامه نویس، دیگر تعیین نمی‌کند که کدام شبکه عصبی در واقع پرامپت را پردازش می‌کند.

کالبدشکافی معماری چهار لایه

طبق بررسی‌های فنی، فرآیند یک درخواست AI به چهار لایه مجزا تقسیم می‌شود. توسعه‌دهندگان اغلب به‌اشتباه این لایه‌ها را در یک کلمه یعنی «هوش مصنوعی» خلاصه می‌کنند، اما هر کدام مرزهای عملیاتی متفاوتی دارند:

۱. اپلیکیشن و SDK: این لایه درخواست را می‌سازد و پاسخ را به اشیای کد قابل استفاده تبدیل می‌کند. وظایف این بخش شامل سریال‌سازی (Serialization)، اعتبارسنجی، مدیریت تلاش‌های مجدد (Retries)، تعیین مهلت زمانی (Timeouts) و ابزارهای کمکی برای استریمینگ است.
۲. درگاه API (Gateway): این لایه مسئول احراز هویت، مسیریابی، اعمال سیاست‌ها و نقشه‌برداری پروتکل است (مثلاً تبدیل یک درخواست سبک OpenAI به فرمتی که Anthropic درک کند). این ساختار مشابه الگوی Audio Gateway است که در آن لایه‌ی مدیریت درخواست از هسته‌ی پردازشی تفکیک می‌شود تا کارایی سیستم بهینه گردد.
۳. لایه سرویس‌دهی (Serving Layer): مدیریت زمان‌بندی (Scheduling)، دسته‌بندی (Batching)، استریمینگ و معیارهای عملکرد در این لایه قرار دارد. وظیفه اصلی این بخش، تبدیل خروجی خام مدل به یک پاسخ JSON در قالب API است.
۴. Runtime استنتاج (Inference Runtime): اینجاست که وزن‌های واقعی مدل قرار دارند تا توکن‌های پرامپت را به توکن‌های تولیدی تبدیل کنند. در این لایه، پرامپت توکن‌گذاری شده، مدل Logitها را تولید می‌کند و یک استراتژی تولید، شناسه‌های توکن جدید را انتخاب می‌نماید.

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

تفاوت SDKها و نقاط اتصال (Endpoints)

یک SDK صرفاً یک پوشش (Wrapper) برای راحتی است و نه خودِ مدل. SDK احراز هویت و هدرهای پیش‌فرض را مدیریت می‌کند، اما همان کار را می‌توان با یک کلاینت HTTP خام مانند httpx انجام داد.

برای مثال، یک درخواست بومی (Native) به آدرس https://api.anthropic.com/v1/messages نیاز به هدرهای خاصی دارد، مانند anthropic-version: 2023-06-01 و content-type: application/json. بدنه درخواست نیز باید شامل model: "claude-sonnet-4-6" و max_tokens: 100 باشد. پاسخ بومی این سیستم نیز از یک آرایه content[] برای داده‌های خود استفاده می‌کند.

در مقابل، SDK شرکت OpenAI انتظار پاسخی را دارد که از آرایه choices[] استفاده کند. باید توجه داشت که هیچ‌کدام از این ساختارها، خروجی طبیعی یک شبکه عصبی نیستند؛ بلکه قراردادهای API هستند که توسط نرم‌افزارهای پیرامونیِ Runtime تولید شده‌اند. در واقع، تنظیم دقیق ترکیب آدرس، کلید و شناسه تنها راه عبور از خطاهای رایج در این لایه‌های واسط است.

مکانیسم تولید توکن‌ها

در پایین‌ترین سطح، مدل‌های زبانی با اعداد کار می‌کنند. پرامپت فرمت شده و توکن‌گذاری می‌شود و سپس Logitها تولید می‌گردند. یک استراتژی تولید، شناسه‌های توکن جدید را انتخاب کرده و آن‌ها را دوباره به متن تبدیل می‌کند.

همان‌طور که در کتابخانه Transformers شرکت Hugging Face دیده می‌شود، تابع generate() در واقع دنباله‌ای از توکن‌ها (یا در صورت درخواست، یک ModelOutput غنی‌تر) را برمی‌گرداند. این فرآیند با کدی شبیه به این مدیریت می‌شود:

generated_ids = model.generate(**model_inputs, max_new_tokens=50)
text = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]

هیچ قانون جهانی در شبکه‌های عصبی وجود ندارد که اجبار کند نتایج حتماً شامل ساختارهای JSON مانند finish_reason: "stop" یا usage: { "prompt_tokens": 10 } باشند. این شکل عمومی JSON در واقع یک قرارداد شبکه است که توسط لایه سرویس‌دهنده/API ایجاد شده است. پروژه‌هایی مانند vLLM این موضوع را شفاف کرده‌اند؛ آن‌ها ماشین استنتاج (خروجی‌های داخلی درخواست) را از سرور سازگار با OpenAI (اسکیماهای سبک OpenAI) جدا می‌کنند.

انعطاف در مسیریابی و Base URLها

وقتی base_url را تغییر می‌دهید، مسیریابی منعطف می‌شود. یک کلاینت واحد می‌تواند به محیط‌های متنوعی اشاره کند در حالی که سبک فراخوانی تقریباً بدون تغییر می‌ماند:

• ارائه‌دهندگان رسمی مدل: مانند https://api.openai.com/v1 برای OpenAI یا https://api.anthropic.com/v1/ برای لایه سازگاری Anthropic.
• درگاه‌های چند-ارائه‌دهنده: مانند OpenRouter یا LiteLLM.
• پراکسی‌های ابری یا سرورهای سازگار: مانند vLLM.
• Runtimeهای محلی: مانند Ollama (با استفاده از آدرس http://localhost:11434/v1/ و یک کلید جعلی api_key="ollama").

به همین دلیل، جمله‌ی «ما از SDK شرکت OpenAI استفاده می‌کنیم» برای یک معمار سیستم اطلاعات بسیار کمی درباره جریان داده‌ها می‌دهد. سوالات حیاتی این‌ها هستند: چه کسی نقطه اتصال (Endpoint) را کنترل می‌کند؟ کدام شناسه‌ی مدل ارسال می‌شود؟ آیا درگاه (Gateway) می‌تواند درخواست را بازنویسی کند؟ و کدام ویژگی‌های پروتکل در طول ترجمه باقی می‌مانند؟

طیف سازگاری (Compatibility Spectrum)

سازگاری یک وضعیت صفر و یک یا باینری نیست. لایه سازگاری Anthropic اجازه می‌دهد تا مدل Claude را به‌سرعت در ادغام‌های موجود با OpenAI تست و مقایسه کنید، اما برای اکثر اپلیکیشن‌هایی که اولویت آن‌ها استفاده از قابلیت‌های Claude است، این مسیر توصیه شده برای محیط Production نیست.

جزئیات شکاف‌های سازگاری

چندین ویژگی حیاتی در لایه سازگاری به‌طور خاموش نادیده گرفته می‌شوند یا متفاوت مدیریت می‌گردند:

• استفاده از ابزار (Tool Use): پارامتر strict برای فراخوانی توابع (Function Calling) کاملاً نادیده گرفته می‌شود.
• فیلدهای نادیده گرفته شده: مواردی چون response_format و logprobs و چندین فیلد خاص دیگر اجرا نمی‌شوند.
• کارایی و بهینه‌سازی: قابلیت کشینگ پرامپت (Prompt Caching) از طریق این رابط سبک OpenAI پشتیبانی نمی‌شود.
• مدیریت پیام‌ها: پیام‌های سیستم (System) و توسعه‌دهنده (Developer) به‌جای اینکه به عنوان موجودیت‌های مجزا پردازش شوند، استخراج شده و با هم ترکیب می‌گردند.

از آنجایی که برخی فیلدهای پشتیبانی‌نشده به‌طور خاموش نادیده گرفته می‌شوند، یک درخواست می‌تواند وضعیت 200 OK را برگرداند، در حالی که فرض‌های توسعه‌دهنده درباره رفتار مدل کاملاً غلط باشد. به همین ترتیب، Ollama اشاره می‌کند که تنها بخش‌هایی از API شرکت OpenAI را پشتیبانی می‌کند و vLLM نیز لیست خاص خود را از پارامترهای پشتیبانی‌شده و اضافی دارد.

خطرات «کمترین مخرج مشترک»

استفاده از یک درگاه جهانی اغلب منجر به باگ‌های تولیدی می‌شود؛ جایی که کد وضعیت 200 OK را برمی‌گرداند اما رفتار مورد نظر — مثلاً اسکیماهای سخت‌گیرانه JSON — نادیده گرفته شده است. این امر منجر به یک «ترجمه با اتلاف» (Lossy Translation) می‌شود که در آن توسعه‌دهنده محدودیت‌های دقت درگاه را می‌پذیرد تا در زمان اولیه کدنویسی صرفه‌جویی کند.

خودِ فیلد model نیز صرفاً یک درخواست است. یک درگاه ممکن است شناسه‌ای مانند anthropic/claude-sonnet-4.6 را به یک منطقه (Region) خاص متصل کند، در صورت خرابی به ارائه‌دهنده دیگری که همان مدل متن‌باز را میزبانی می‌کند منتقل شود، یا یک نام مستعار سازمانی اعمال کند. در محیط عملیاتی، ثبت (Log) ارائه‌دهنده نهایی، نسخه مدل، شناسه درخواست و تصمیمات مسیریابی حیاتی است.

مسیرهای پیشنهادی برای پیاده‌سازی

برای محیط‌های عملیاتی، انتخاب SDK باید با مقیاس و نیازهای واقعی مطابقت داشته باشد:

• اپلیکیشن‌های متمرکز بر Claude: حتماً از Anthropic SDK بومی استفاده کنید. این کار بهترین پوشش ویژگی‌های Claude را فراهم کرده و از محدودیت‌های لایه سازگاری جلوگیری می‌کند.
• اپلیکیشن‌های متمرکز بر OpenAI: برای بهترین دسترسی به ویژگی‌های OpenAI از OpenAI SDK بومی استفاده نمایید.
• ارزیابی مدل‌ها (Evaluation): برای جابه‌جایی سریع میان مدل‌ها از یک رابط یا درگاه سازگار با OpenAI استفاده کنید، اما آگاه باشید که مقایسه‌های ویژگی‌ها ممکن است ناقص باشد.
• تولید متن قابل انتقال (Portable): برای ادغام‌های ساده از یک قرارداد درگاه مشترک استفاده کنید، در حالی که ریسک «کمترین مخرج مشترک» را می‌پذیرید.
• استفاده سنگین از ابزارها یا مدل‌های چندوجهی (Multimodal): از آداپتورهای بومی ارائه‌دهنده در پشت رابط کاربری خودتان استفاده کنید تا رفتار سیستم صریح و قابل تست باشد.
• توسعه محلی: برای راحتی از نقاط اتصال سازگار Ollama یا vLLM استفاده کنید.

طراحی برای پایداری در سیستم‌های چند-ارائه‌دهنده

برای اپلیکیشن‌های جدی که از چندین ارائه‌دهنده استفاده می‌کنند، بهترین رویکرد ایجاد یک رابط داخلی کوچک با استفاده از Protocol در پایتون است تا ترجمه‌های ناقص و اتلافی برای برنامه‌نویس দৃশ্য‌پذیر باشد:

from typing import Protocol

class TextModel(Protocol):
    def generate(self, prompt: str) -> str: ...

class ClaudeModel:
    def generate(self, prompt: str) -> str:
        # Native Anthropic SDK implementation
        ... 

class OpenAIModel:
    def generate(self, prompt: str) -> str:
        # Native OpenAI SDK implementation
        ... 

اگر به‌جای این روش، یک درگاه جهانی انتخاب می‌شود، توسعه‌دهندگان باید تست‌های قراردادی (Contract Tests) را برای هر ویژگی مورد نیاز پیاده کنند، از جمله:

• متن ساده و استریمینگ (Streaming)
• آرگومان‌های فراخوانی ابزار (Tool Call Arguments)
• خروجی‌های ساختاریافته سخت‌گیرانه (Strict Structured Output)
• ورودی‌های تصویری و دلایل توقف (Stop Reasons)
• محاسبه میزان مصرف (Usage Accounting) و طبقه‌بندی خطاهای قابل تلاش مجدد.

این جداسازی معماری از این اشتباه رایج جلوگیری می‌کند که تصور شود «سازگار با OpenAI» به معنای «یکسان با OpenAI» است. هنگام تعویض ارائه‌دهنده، توسعه‌دهندگان باید از تکیه بر تست‌های ساده «Hello World» اجتناب کرده و در عوض حالت‌های شکست خاص مانند رویدادهای استریمینگ، آرگومان‌های ابزار و محاسبه مصرف را تأیید کنند.

گام بعدی شما

• اگر از لایه سازگاری استفاده می‌کنید، حتماً تست‌های قراردادی (Contract Tests) برای خروجی‌های ساختاریافته (Structured Output) بنویسید.
• برای کاهش هزینه‌ها و افزایش سرعت در Claude، از روش‌های بومی کشینگ پرامپت به‌جای SDK شرکت OpenAI استفاده کنید.
• در لاگ‌های سیستم خود، علاوه بر نام مدل، نسخه دقیق و تصمیمات مسیریابی (Routing) را ثبت کنید.

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