SDK چیست؟ تفاوت SDK و API و آموزش استفاده از SDK هوش مصنوعی

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

SDK مخفف Software Development Kit و به معنای «کیت توسعه نرم‌افزار» است. SDK مجموعه‌ای از ابزارها، کتابخانه‌ها، مستندات، انواع داده، نمونه‌کدها و قابلیت‌های کمکی است که توسعه یک نرم‌افزار برای یک پلتفرم یا اتصال آن به یک سرویس را ساده‌تر می‌کند.

برای مثال، یک سرویس هوش مصنوعی ممکن است یک REST API ارائه دهد. توسعه‌دهنده می‌تواند مستقیماً با ارسال درخواست HTTP از آن استفاده کند، اما SDK کارهایی مانند موارد زیر را ساده‌تر می‌کند:

• ساخت درخواست
• تنظیم هدرهای احراز هویت
• تبدیل داده‌ها به JSON
• پردازش پاسخ
• مدیریت خطا
• Retry
• Timeout
• Streaming
• بارگذاری فایل
• تعریف Type برای ورودی و خروجی
• استفاده از حالت هم‌زمان و غیرهم‌زمان

در این مقاله، ابتدا مفهوم SDK را دقیق بررسی می‌کنیم و سپس با استفاده از OpenAI SDK، یک برنامه Python و TypeScript را به API درواره متصل می‌کنیم.

SDK چیست؟

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

یک SDK کامل ممکن است شامل اجزای زیر باشد:

• کتابخانه یا Package
• API Client
• مستندات فنی
• نمونه‌کد
• مدل‌های داده
• ابزارهای تست
• Debugger
• Compiler
• CLI
• شبیه‌ساز
• فایل‌های پیکربندی
• ابزارهای ساخت و انتشار
• راهنمای مهاجرت میان نسخه‌ها

محتوای SDK به کاربرد آن بستگی دارد. برای مثال، Android SDK شامل ابزارهای ساخت، Debug و اجرای اپلیکیشن اندروید است؛ اما SDK یک سرویس هوش مصنوعی ممکن است بیشتر شامل API Client، Typeها، مدیریت Streaming و کلاس‌های خطا باشد.

در عمل، بسیاری از سرویس‌های وب اصطلاح SDK را برای یک کتابخانه رسمی استفاده می‌کنند که ارتباط با API آن‌ها را در یک زبان برنامه‌نویسی خاص ساده می‌کند.

SDK مخفف چیست؟

SDK مخفف عبارت زیر است:

Software Development Kit

ترجمه رایج آن در فارسی «کیت توسعه نرم‌افزار» است.

واژه Kit نشان می‌دهد که SDK معمولاً فقط یک تابع یا API منفرد نیست، بلکه مجموعه‌ای از ابزارهای مرتبط برای توسعه‌دهنده است.

تفاوت SDK و API چیست؟

API و SDK رقیب یکدیگر نیستند. SDK معمولاً روشی ساده‌تر و زبان‌محور برای استفاده از API فراهم می‌کند.

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

POST /v1/chat/completions
Authorization: Bearer API_KEY
Content-Type: application/json

SDK این قرارداد را به کد قابل‌استفاده در زبان برنامه‌نویسی تبدیل می‌کند:

completion = client.chat.completions.create(
    model=MODEL_ID,
    messages=[
        {
            "role": "user",
            "content": "یک توضیح کوتاه درباره رایانش ابری بنویس.",
        }
    ],
)

در پشت صحنه، SDK همچنان یک درخواست HTTP به API ارسال می‌کند.

یک مثال ساده از API و SDK

فرض کنید برنامه باید وضعیت آب‌وهوا را از یک سرویس دریافت کند.

استفاده مستقیم از API:

import requests


response = requests.get(
    "https://api.example.com/v1/weather",
    params={"city": "Tehran"},
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
    timeout=10,
)

response.raise_for_status()
weather = response.json()

print(weather["temperature"])

استفاده از SDK:

from example_weather import WeatherClient


client = WeatherClient(api_key="YOUR_API_KEY")

weather = client.get_weather(city="Tehran")

print(weather.temperature)

در نسخه SDK، جزئیات URL، Header، JSON و تبدیل پاسخ داخل کتابخانه مدیریت شده‌اند.

تفاوت SDK و Library چیست؟

Library یا کتابخانه مجموعه‌ای از کدهای قابل‌استفاده مجدد برای انجام یک یا چند وظیفه است. SDK می‌تواند شامل یک یا چند Library باشد، اما معمولاً دامنه وسیع‌تری دارد.

برای مثال:

• یک کتابخانه تاریخ، عملیات مربوط به تاریخ و زمان را انجام می‌دهد.
• یک SDK پرداخت ممکن است شامل API Client، مدل‌های تراکنش، نمونه‌کد، مستندات، ابزار تست و Webhook Validator باشد.

در سرویس‌های ابری، مرز میان Library و SDK همیشه کاملاً مشخص نیست. گاهی یک Package رسمی با عنوان SDK منتشر می‌شود، حتی اگر بخش اصلی آن یک کتابخانه API Client باشد.

تفاوت SDK و Framework چیست؟

Framework ساختار کلی برنامه را تعیین می‌کند و معمولاً کنترل بخشی از جریان اجرای نرم‌افزار را در اختیار می‌گیرد. SDK مجموعه‌ای از ابزارهاست که توسعه‌دهنده می‌تواند در ساختار دلخواه خود از آن استفاده کند.

برای مثال:

• Django و FastAPI فریم‌ورک توسعه وب هستند.
• OpenAI Python Package یک SDK یا API Client است.
• یک برنامه FastAPI می‌تواند از OpenAI SDK برای ارتباط با یک مدل استفاده کند.

تفاوت اصلی را می‌توان این‌گونه خلاصه کرد:

شما SDK را در برنامه خود فراخوانی می‌کنید؛ اما Framework معمولاً بخش مهمی از نحوه اجرای برنامه شما را تعیین می‌کند.

تفاوت SDK و CLI چیست؟

CLI یا Command-Line Interface ابزاری برای اجرای دستورها در Terminal است.

برای مثال:

example models list

اما SDK از داخل کد استفاده می‌شود:

models = client.models.list()

یک پلتفرم می‌تواند هم‌زمان API، SDK و CLI داشته باشد. CLI نیز ممکن است در پشت صحنه از همان SDK استفاده کند.

تفاوت SDK و Package چیست؟

Package شکل بسته‌بندی و توزیع کد است. SDK ممکن است در قالب یک یا چند Package منتشر شود.

برای نمونه:

pip install openai

یا:

npm install openai

در این مثال، openai یک Package قابل‌نصب است که API Client و قابلیت‌های لازم برای استفاده از سرویس را فراهم می‌کند.

SDK از چه اجزایی تشکیل می‌شود؟

API Client

API Client مسئول ساخت و ارسال درخواست‌ها به سرویس است. این بخش معمولاً موارد زیر را مدیریت می‌کند:

• Base URL
• API Key
• Headerها
• Query Parameterها
• بدنه درخواست
• Serialization
• Deserialization

مدل‌های ورودی و خروجی

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

نمونه TypeScript:

type ChatRequest = {
  model: string;
  messages: Array<{
    role: "system" | "user" | "assistant";
    content: string;
  }>;
};

مدیریت خطا

به‌جای اینکه توسعه‌دهنده تمام Status Codeها را به‌صورت دستی بررسی کند، SDK می‌تواند خطاهایی با معنای روشن‌تر ایجاد کند:

• خطای اتصال
• Timeout
• احراز هویت نامعتبر
• Rate Limit
• ورودی نامعتبر
• خطای داخلی سرویس
• مدل در دسترس نیست

Retry

برخی SDKها برای خطاهای موقت، درخواست را با سیاست مشخص دوباره ارسال می‌کنند. Retry باید محدود و کنترل‌شده باشد؛ زیرا تکرار نامحدود می‌تواند هزینه، تأخیر و بار سیستم را افزایش دهد.

Streaming

در تولید متن یا صوت، ممکن است نتیجه به‌صورت تدریجی دریافت شود. SDK پردازش Stream را ساده‌تر می‌کند.

Pagination

اگر API فهرست بزرگی از داده‌ها را در چند صفحه برگرداند، SDK می‌تواند پیمایش صفحات را مدیریت کند.

File Upload

SDK ممکن است تبدیل فایل به درخواست Multipart، خواندن Stream و ارسال Metadata را مدیریت کند.

مستندات و نمونه‌ها

یک SDK بدون مستندات روشن، تجربه توسعه مناسبی ایجاد نمی‌کند. مستندات باید نصب، پیکربندی، مدیریت خطا و مثال‌های عملی را پوشش دهند.

انواع SDK

SDK سیستم‌عامل

برای ساخت برنامه روی سیستم‌عامل خاص استفاده می‌شود؛ مانند Android SDK یا Windows SDK.

SDK زبان برنامه‌نویسی

برای استفاده از یک سرویس در زبان خاص ارائه می‌شود؛ مانند Python SDK، Java SDK یا JavaScript SDK.

SDK سرویس ابری

ارتباط با فضای ذخیره‌سازی، پایگاه داده، صف پیام یا سایر خدمات ابری را ساده می‌کند.

SDK پرداخت

قابلیت‌هایی مانند ساخت تراکنش، تأیید پرداخت، استرداد وجه و بررسی Webhook را ارائه می‌دهد.

SDK موبایل

برای افزودن Analytics، تبلیغات، پرداخت، Push Notification یا ورود کاربران به اپلیکیشن موبایل استفاده می‌شود.

SDK هوش مصنوعی

دسترسی به مدل‌های متنی، تصویری، صوتی، ویدیویی، Embedding و Agentها را ساده می‌کند.

مزایای استفاده از SDK

توسعه سریع‌تر

SDK بخش زیادی از کدهای تکراری مربوط به HTTP، Header، JSON و خطاها را آماده می‌کند.

خوانایی بیشتر کد

این کد:

client.chat.completions.create(...)

از ساخت دستی URL، Header و بدنه درخواست خواناتر است.

کاهش خطاهای پیاده‌سازی

مدل‌های داده و Typeها احتمال اشتباه در نام پارامترها یا ساختار درخواست را کاهش می‌دهند.

پشتیبانی از قابلیت‌های پیچیده

پیاده‌سازی Streaming، File Upload، WebSocket یا Pagination با SDK ساده‌تر است.

هماهنگی با تغییرات API

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

تجربه یکسان در پروژه

SDK می‌تواند الگوی واحدی برای Timeout، Retry، ثبت خطا و احراز هویت ایجاد کند.

معایب استفاده از SDK

وابستگی به نسخه SDK

به‌روزرسانی یک نسخه اصلی ممکن است شامل Breaking Change باشد و بخشی از کد برنامه را ناسازگار کند.

تأخیر در پشتیبانی از قابلیت جدید

گاهی قابلیت جدید ابتدا در REST API منتشر می‌شود و SDK بعداً از آن پشتیبانی می‌کند.

کاهش کنترل سطح پایین

در استفاده مستقیم از HTTP، توسعه‌دهنده بر Header، Connection Pool، Serialization و Transport کنترل بیشتری دارد.

افزایش وابستگی به ارائه‌دهنده

اگر Typeها و کلاس‌های SDK در تمام لایه‌های برنامه استفاده شوند، مهاجرت به ارائه‌دهنده دیگر دشوارتر خواهد شد.

افزایش حجم برنامه

این موضوع به‌خصوص در اپلیکیشن‌های موبایل، مرورگر و Serverless اهمیت دارد.

چه زمانی از SDK استفاده کنیم؟

استفاده از SDK معمولاً انتخاب مناسبی است اگر:

• SDK رسمی و فعال وجود دارد.
• زبان پروژه پشتیبانی می‌شود.
• به Streaming یا File Upload نیاز دارید.
• Type Safety اهمیت دارد.
• می‌خواهید سریع نمونه اولیه بسازید.
• تیم نمی‌خواهد کد HTTP تکراری نگهداری کند.
• SDK امکان تنظیم Base URL را فراهم می‌کند.
• مدیریت خطا و Retry آن قابل تنظیم است.

چه زمانی استفاده مستقیم از API بهتر است؟

در شرایط زیر ممکن است Raw HTTP مناسب‌تر باشد:

• SDK برای زبان شما وجود ندارد.
• قابلیت جدید هنوز در SDK اضافه نشده است.
• حجم نهایی برنامه باید بسیار کم باشد.
• کنترل دقیق Transport ضروری است.
• محیط اجرای شما محدودیت خاصی دارد.
• SDK وابستگی‌های غیرضروری زیادی اضافه می‌کند.
• فقط به یک endpoint ساده نیاز دارید.
• قصد دارید یک SDK داخلی یا عمومی بسازید.

مقایسه درخواست مستقیم HTTP با SDK درواره

آدرس پایه API درواره:

https://api.darvareh.ir/v1

استفاده مستقیم با cURL

curl "https://api.darvareh.ir/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "temperature": 0.2,
    "messages": [
      {
        "role": "system",
        "content": "شما یک دستیار فارسی دقیق و مختصر هستید."
      },
      {
        "role": "user",
        "content": "SDK را در یک پاراگراف توضیح بده."
      }
    ]
  }'

همان درخواست با Python SDK

import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url="https://api.darvareh.ir/v1",
)

completion = client.chat.completions.create(
    model=os.environ["DARVAREH_MODEL"],
    temperature=0.2,
    messages=[
        {
            "role": "system",
            "content": "شما یک دستیار فارسی دقیق و مختصر هستید.",
        },
        {
            "role": "user",
            "content": "SDK را در یک پاراگراف توضیح بده.",
        },
    ],
)

answer = completion.choices[0].message.content

print(answer)

در هر دو روش یک API فراخوانی می‌شود، اما SDK ساخت درخواست و پردازش پاسخ را ساده کرده است.

آموزش استفاده از OpenAI SDK با API درواره در Python

API درواره با ساختار OpenAI سازگار است. بنابراین در بسیاری از پروژه‌ها می‌توان از همان SDK استفاده و آدرس پایه را تغییر داد.

کتابخانه رسمی Python شامل Typeهای ورودی و خروجی و Clientهای هم‌زمان و غیرهم‌زمان است. جزئیات نسخه فعلی در مخزن OpenAI Python SDK منتشر می‌شود.

نصب SDK

pip install openai

تنظیم متغیرهای محیطی

export DARVAREH_API_KEY="YOUR_API_KEY"
export DARVAREH_MODEL="YOUR_MODEL_ID"

ساخت Client قابل‌استفاده مجدد

import os

from openai import OpenAI


def create_ai_client() -> OpenAI:
    return OpenAI(
        api_key=os.environ["DARVAREH_API_KEY"],
        base_url="https://api.darvareh.ir/v1",
        timeout=30.0,
        max_retries=2,
    )

بهتر است در هر درخواست HTTP نرم‌افزار، Client جدید نسازید. یک Client با طول عمر مناسب ایجاد کنید تا Connection Pool قابل‌استفاده مجدد باشد.

ساخت سرویس تولید متن

import os

from openai import OpenAI


class TextGenerationService:
    def __init__(self, client: OpenAI, model: str) -> None:
        self.client = client
        self.model = model

    def generate(self, prompt: str) -> str:
        completion = self.client.chat.completions.create(
            model=self.model,
            temperature=0.2,
            messages=[
                {
                    "role": "system",
                    "content": (
                        "شما یک دستیار فارسی هستید. "
                        "پاسخ‌ها باید دقیق، روشن و بدون اطلاعات ساختگی باشند."
                    ),
                },
                {
                    "role": "user",
                    "content": prompt,
                },
            ],
        )

        content = completion.choices[0].message.content

        if not content:
            raise ValueError("مدل پاسخ متنی تولید نکرد.")

        return content


client = create_ai_client()

service = TextGenerationService(
    client=client,
    model=os.environ["DARVAREH_MODEL"],
)

result = service.generate(
    "سه تفاوت API و SDK را در قالب فهرست توضیح بده."
)

print(result)

قرار دادن فراخوانی SDK داخل یک Service باعث می‌شود منطق ارائه‌دهنده در تمام برنامه پراکنده نشود.

مدیریت خطاهای SDK در Python

فقط استفاده از try/except Exception برای یک برنامه Production کافی نیست. خطاهای موقت و دائمی باید رفتار متفاوتی داشته باشند.

from openai import (
    APIConnectionError,
    APIStatusError,
    APITimeoutError,
    RateLimitError,
)


def generate_with_error_handling(
    service: TextGenerationService,
    prompt: str,
) -> str:
    try:
        return service.generate(prompt)

    except APITimeoutError as error:
        raise RuntimeError(
            "زمان انتظار برای دریافت پاسخ به پایان رسید."
        ) from error

    except RateLimitError as error:
        raise RuntimeError(
            "ظرفیت درخواست موقتاً تکمیل است."
        ) from error

    except APIConnectionError as error:
        raise RuntimeError(
            "اتصال به سرویس هوش مصنوعی برقرار نشد."
        ) from error

    except APIStatusError as error:
        status_code = error.status_code

        if 400 <= status_code < 500:
            raise RuntimeError(
                f"درخواست توسط سرویس رد شد: {status_code}"
            ) from error

        raise RuntimeError(
            f"خطای موقت سرویس: {status_code}"
        ) from error

در عمل بهتر است خطاهای SDK به خطاهای داخلی برنامه تبدیل شوند. در این صورت، لایه‌های بالاتر به کلاس‌های یک ارائه‌دهنده خاص وابسته نمی‌شوند.

Retry را برای چه خطاهایی فعال کنیم؟

Retry معمولاً برای خطاهای موقت مناسب است:

• Timeout
• قطع موقت اتصال
• خطاهای ۵۰۰
• خطای ۵۰۲
• خطای ۵۰۳
• خطای ۵۰۴
• بعضی خطاهای Rate Limit

اما درخواست‌هایی با خطاهای زیر نباید بدون اصلاح تکرار شوند:

• API Key نامعتبر
• شناسه مدل اشتباه
• ورودی نامعتبر
• دسترسی ناکافی
• فرمت اشتباه فایل
• تجاوز از محدودیت ثابت ورودی

الگوی مناسب Retry از Exponential Backoff و Jitter استفاده می‌کند. همچنین تعداد تلاش‌ها باید محدود باشد.

دریافت پاسخ Streaming با Python SDK

در رابط چت، بهتر است کاربر دریافت پاسخ را از همان توکن‌های ابتدایی مشاهده کند.

import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url="https://api.darvareh.ir/v1",
    timeout=60.0,
)

stream = client.chat.completions.create(
    model=os.environ["DARVAREH_MODEL"],
    stream=True,
    messages=[
        {
            "role": "user",
            "content": "SDK چیست و چه کاربردی دارد؟",
        }
    ],
)

for chunk in stream:
    content = chunk.choices[0].delta.content

    if content:
        print(content, end="", flush=True)

SDK رسمی Python از دریافت Streaming پشتیبانی می‌کند و جزئیات رابط فعلی آن در مستندات OpenAI Python قابل بررسی است.

استفاده غیرهم‌زمان در Python

برای برنامه‌هایی که چند درخواست ورودی هم‌زمان دارند، استفاده از Client غیرهم‌زمان می‌تواند مناسب‌تر باشد:

import asyncio
import os

from openai import AsyncOpenAI


client = AsyncOpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url="https://api.darvareh.ir/v1",
    timeout=30.0,
    max_retries=2,
)


async def generate_text(prompt: str) -> str:
    completion = await client.chat.completions.create(
        model=os.environ["DARVAREH_MODEL"],
        temperature=0.2,
        messages=[
            {
                "role": "user",
                "content": prompt,
            }
        ],
    )

    content = completion.choices[0].message.content

    if not content:
        raise ValueError("پاسخی دریافت نشد.")

    return content


async def main() -> None:
    result = await generate_text(
        "تفاوت کتابخانه و فریم‌ورک را توضیح بده."
    )

    print(result)


asyncio.run(main())

استفاده از Client Async به‌تنهایی ظرفیت نامحدود ایجاد نمی‌کند. تعداد درخواست‌های هم‌زمان باید با Semaphore، Queue یا Rate Limiter کنترل شود.

آموزش استفاده از SDK در Node.js و TypeScript

کتابخانه رسمی JavaScript و TypeScript در مخزن OpenAI Node SDK نگهداری می‌شود.

نصب Package

npm install openai

تنظیم متغیرهای محیطی

export DARVAREH_API_KEY="YOUR_API_KEY"
export DARVAREH_MODEL="YOUR_MODEL_ID"

ساخت Client

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DARVAREH_API_KEY,
  baseURL: "https://api.darvareh.ir/v1",
  timeout: 30_000,
  maxRetries: 2,
});

در SDK جاوااسکریپت نام گزینه baseURL است، درحالی‌که در نسخه Python از base_url استفاده می‌شود.

ارسال درخواست

const model = process.env.DARVAREH_MODEL;

if (!model) {
  throw new Error("DARVAREH_MODEL is not configured.");
}

const completion = await client.chat.completions.create({
  model,
  temperature: 0.2,
  messages: [
    {
      role: "system",
      content: "شما یک دستیار فارسی دقیق و مختصر هستید.",
    },
    {
      role: "user",
      content: "تفاوت SDK و API را با یک مثال توضیح بده.",
    },
  ],
});

const answer = completion.choices[0]?.message?.content;

if (!answer) {
  throw new Error("No text response was returned.");
}

console.log(answer);

Streaming در Node.js

const stream = await client.chat.completions.create({
  model,
  stream: true,
  messages: [
    {
      role: "user",
      content: "مزایای استفاده از SDK را توضیح بده.",
    },
  ],
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;

  if (content) {
    process.stdout.write(content);
  }
}

برای ارسال Stream به مرورگر می‌توان از Server-Sent Events یا WebSocket استفاده کرد. انتخاب آن‌ها به نوع تعامل و معماری محصول بستگی دارد.

استفاده از SDK در مرورگر درست است؟

قرار دادن کلید API داخل JavaScript مرورگر، اپلیکیشن موبایل یا افزونه عمومی مناسب نیست. کاربر می‌تواند کلید موجود در Bundle، Network Request یا حافظه برنامه را استخراج کند.

معماری پیشنهادی:

مرورگر یا اپلیکیشن
        ↓
سرور نرم‌افزار شما
        ↓
قوانین، سهمیه و ثبت مصرف
        ↓
SDK و API درواره
        ↓
مدل هوش مصنوعی

مزایای این معماری:

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

جلوگیری از Vendor Lock-in هنگام استفاده از SDK

استفاده مستقیم از کلاس‌های یک SDK در تمام لایه‌های برنامه، مهاجرت را دشوار می‌کند. بهتر است یک Interface داخلی تعریف شود.

تعریف Interface در Python

from typing import Protocol


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

پیاده‌سازی با SDK

from openai import OpenAI


class DarvarehTextGenerator:
    def __init__(
        self,
        client: OpenAI,
        model: str,
    ) -> None:
        self.client = client
        self.model = model

    def generate(self, prompt: str) -> str:
        completion = self.client.chat.completions.create(
            model=self.model,
            temperature=0.2,
            messages=[
                {
                    "role": "user",
                    "content": prompt,
                }
            ],
        )

        content = completion.choices[0].message.content

        if not content:
            raise ValueError("Empty response")

        return content

استفاده در منطق برنامه

class ArticleService:
    def __init__(self, generator: AITextGenerator) -> None:
        self.generator = generator

    def create_outline(self, topic: str) -> str:
        return self.generator.generate(
            f"برای موضوع زیر ساختار مقاله تهیه کن:\n{topic}"
        )

اکنون ArticleService نمی‌داند از چه SDK یا ارائه‌دهنده‌ای استفاده می‌شود. این طراحی تست، تغییر مدل و مهاجرت را ساده‌تر می‌کند.

آیا استفاده از API سازگار با OpenAI یعنی سازگاری کامل؟

خیر. سازگاری API معمولاً به این معناست که بخش مهمی از ساختار درخواست‌ها، پاسخ‌ها و احراز هویت مشابه است. بااین‌حال ممکن است قابلیت‌های زیر میان مدل‌ها و ارائه‌دهندگان متفاوت باشند:

• نام endpoint
• پارامترهای پشتیبانی‌شده
• نقش‌های پیام
• Streaming
• Tool Calling
• Structured Outputs
• ورودی تصویر
• تولید صوت
• تولید تصویر
• تعداد توکن Context
• فرمت خطا
• Usage Metadata
• محدودیت نرخ

بنابراین هر قابلیت باید روی مدل و مسیر واقعی آزمایش شود. سازگاری نباید به‌عنوان تضمین یکسان‌بودن تمام ویژگی‌ها در نظر گرفته شود.

نسخه‌بندی SDK

بسیاری از Packageها از Semantic Versioning استفاده می‌کنند:

MAJOR.MINOR.PATCH

برای مثال:

3.7.2

معنای معمول:

• MAJOR: تغییر ناسازگار
• MINOR: قابلیت جدید سازگار
• PATCH: اصلاح خطای سازگار

تعریف رسمی این قرارداد در Semantic Versioning 2.0.0 منتشر شده است.

البته هر پروژه ممکن است سیاست نسخه‌بندی متفاوتی داشته باشد. پیش از به‌روزرسانی باید Changelog و Migration Guide همان SDK بررسی شود.

آیا نسخه SDK را ثابت کنیم؟

در محیط Production باید نسخه وابستگی‌ها قابل بازتولید باشد.

در Python می‌توان از فایل Lock یا نسخه مشخص استفاده کرد:

openai==X.Y.Z

در Node.js نیز بهتر است فایل Lock مانند موارد زیر در مخزن نگهداری شود:

• package-lock.json
• pnpm-lock.yaml
• yarn.lock

اما ثابت‌ماندن دائمی روی یک نسخه قدیمی نیز مناسب نیست. فرایند پیشنهادی:

1. بررسی دوره‌ای نسخه جدید
2. مطالعه Changelog
3. اجرای تست‌های خودکار
4. آزمایش روی محیط Staging
5. انتشار کنترل‌شده
6. امکان Rollback

معیارهای انتخاب SDK مناسب

رسمی یا غیررسمی بودن

SDK رسمی معمولاً هماهنگی بیشتری با API دارد. SDK غیررسمی ممکن است قابلیت‌های مفیدی ارائه کند، اما وضعیت نگهداری آن باید بررسی شود.

کیفیت Typeها

در TypeScript و زبان‌های Typed، پوشش کامل Typeها تجربه توسعه را بهتر می‌کند.

پشتیبانی از Async

برای سرویس‌های پرترافیک، وجود Client غیرهم‌زمان اهمیت دارد.

مدیریت Streaming

بررسی کنید SDK از Stream موردنیاز محصول پشتیبانی می‌کند یا خیر.

امکان تنظیم Base URL

این قابلیت برای استفاده از API Gateway یا سرویس‌های سازگار اهمیت زیادی دارد.

کنترل Timeout و Retry

SDK باید اجازه دهد سیاست‌های شبکه را براساس نیاز محصول تنظیم کنید.

کیفیت خطاها

خطا باید Status Code، پیام و در صورت وجود شناسه درخواست را قابل‌دسترسی کند.

وضعیت نگهداری

تعداد نسخه‌ها به‌تنهایی کافی نیست. فعالیت مخزن، Changelog، مستندات و زمان پاسخ به Issueها را بررسی کنید.

اندازه و وابستگی‌ها

در محیط‌های Serverless، موبایل و Edge، اندازه Package و سازگاری Runtime مهم است.

اشتباهات رایج هنگام استفاده از SDK

ساخت Client در هر درخواست

این کار می‌تواند مانع استفاده مناسب از Connection Pool شود. Client را با طول عمر مناسب مدیریت کنید.

استفاده از Timeout نامحدود

هر درخواست شبکه باید Timeout مشخصی داشته باشد.

Retry روی تمام خطاها

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

قراردادن کلید در Frontend

کلید API باید در سمت سرور نگهداری شود.

انتشار مستقیم خطای SDK برای کاربر

پیام داخلی سرویس ممکن است فنی یا نامناسب باشد. خطاها را به پیام‌های کنترل‌شده برنامه تبدیل کنید.

وابستگی منطق کسب‌وکار به Typeهای SDK

Typeهای ارائه‌دهنده را در مرز زیرساخت نگه دارید و در داخل برنامه از مدل‌های دامنه خود استفاده کنید.

نداشتن ثبت Usage

برای هر درخواست، مدل، قابلیت، زمان پاسخ، وضعیت و میزان مصرف را ثبت کنید.

به‌روزرسانی خودکار بدون تست

نسخه جدید SDK ممکن است رفتار یا Typeها را تغییر دهد. به‌روزرسانی باید از مسیر تست و Staging عبور کند.

ثابت‌کردن شناسه مدل در کد

شناسه مدل را در تنظیمات یا متغیر محیطی قرار دهید.

فرض سازگاری کامل همه مدل‌ها

قابلیت‌هایی مانند Tool Calling یا ورودی تصویر باید برای هر مدل به‌صورت جداگانه بررسی شوند.

اگر بخواهیم SDK داخلی بسازیم چه اجزایی لازم است؟

برای پروژه‌های بزرگ بهتر است یک SDK یا Client داخلی میان منطق محصول و ارائه‌دهندگان مدل قرار گیرد.

این لایه می‌تواند شامل موارد زیر باشد:

• Interface واحد تولید متن
• Interface تولید تصویر و صوت
• تنظیم Base URL
• مدیریت کلیدها
• Timeout
• Retry Policy
• Error Mapping
• ثبت Usage
• Trace ID
• Logging
• Model Routing
• Fallback
• Circuit Breaker
• مدیریت Streaming
• اعتبارسنجی خروجی
• تبدیل پاسخ ارائه‌دهنده به مدل داخلی
• تست Mock
• مستندات
• Changelog

نمونه Interface عمومی:

from dataclasses import dataclass
from typing import Protocol


@dataclass
class GenerationRequest:
    prompt: str
    model: str | None = None
    temperature: float = 0.2
    max_output_tokens: int | None = None


@dataclass
class GenerationResult:
    text: str
    model: str
    input_tokens: int | None
    output_tokens: int | None
    request_id: str | None


class AIProvider(Protocol):
    def generate(
        self,
        request: GenerationRequest,
    ) -> GenerationResult:
        ...

این طراحی اجازه می‌دهد ارائه‌دهنده یا SDK زیرین تغییر کند، بدون اینکه منطق اصلی محصول بازنویسی شود.

تست کدی که به SDK وابسته است

نباید تمام تست‌ها درخواست واقعی به مدل ارسال کنند. Interface داخلی امکان ساخت Fake یا Mock را فراهم می‌کند.

class FakeTextGenerator:
    def generate(self, prompt: str) -> str:
        return "پاسخ آزمایشی ثابت"


def test_article_outline() -> None:
    service = ArticleService(
        generator=FakeTextGenerator()
    )

    result = service.create_outline(
        "SDK چیست؟"
    )

    assert result == "پاسخ آزمایشی ثابت"

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

چک‌لیست استفاده از SDK در Production

پیش از انتشار بررسی کنید:

• نسخه SDK مشخص و ثبت شده است.
• کلید API در Secret Manager یا متغیر محیطی قرار دارد.
• Base URL از تنظیمات خوانده می‌شود.
• شناسه مدل قابل تغییر است.
• Timeout تعیین شده است.
• Retry محدود و هدفمند است.
• خطاهای SDK به خطاهای داخلی تبدیل می‌شوند.
• درخواست‌های هم‌زمان محدود شده‌اند.
• Usage و هزینه ثبت می‌شود.
• اطلاعات حساس وارد Log نمی‌شوند.
• Streaming در قطع اتصال مدیریت می‌شود.
• تست واحد از API واقعی مستقل است.
• Integration Test وجود دارد.
• Changelog پیش از به‌روزرسانی بررسی می‌شود.
• امکان تغییر مدل یا مسیر فراهم است.
• کلید API داخل Frontend قرار نگرفته است.

پرسش‌های متداول

SDK چیست؟

SDK یا Software Development Kit مجموعه‌ای از کتابخانه‌ها، ابزارها، مستندات و نمونه‌کدهاست که توسعه نرم‌افزار برای یک پلتفرم یا سرویس را ساده می‌کند.

تفاوت SDK و API چیست؟

API قرارداد ارتباط با سرویس است، درحالی‌که SDK مجموعه ابزارهایی است که استفاده از آن API را در یک زبان برنامه‌نویسی آسان‌تر می‌کند.

آیا SDK بدون API کار می‌کند؟

بله. همه SDKها برای سرویس‌های اینترنتی ساخته نشده‌اند. برای مثال، SDK سیستم‌عامل می‌تواند شامل Compiler، Emulator و ابزارهای محلی باشد. اما SDK سرویس‌های ابری معمولاً از یک API استفاده می‌کند.

آیا API داخل SDK قرار دارد؟

SDK معمولاً Client و ابزارهای استفاده از API را ارائه می‌کند. خود سرویس API روی سرور اجرا می‌شود، اما قرارداد و توابع دسترسی به آن در SDK بازنمایی می‌شوند.

تفاوت SDK و کتابخانه چیست؟

کتابخانه مجموعه‌ای از کدهای قابل‌استفاده مجدد است. SDK می‌تواند کتابخانه، مستندات، نمونه‌کد و ابزارهای توسعه را با هم ارائه کند.

آیا OpenAI SDK را می‌توان با درواره استفاده کرد؟

API درواره با ساختار OpenAI سازگار است. در بسیاری از کاربردها می‌توان با تنظیم base_url یا baseURL و انتخاب شناسه مدل، از OpenAI SDK استفاده کرد.

Python SDK بهتر است یا Node.js SDK؟

انتخاب به زبان Backend و معماری پروژه بستگی دارد. هر دو برای ارتباط با API مناسب‌اند. Python در پروژه‌های داده و هوش مصنوعی رایج است و Node.js در Backendهای JavaScript و TypeScript استفاده گسترده‌ای دارد.

آیا SDK هزینه جداگانه دارد؟

بیشتر API Clientهای متن‌باز رایگان هستند، اما استفاده از سرویس زیربنایی براساس تعرفه API محاسبه می‌شود. مجوز هر SDK را جداگانه بررسی کنید.

آیا باید SDK را در Frontend نصب کنیم؟

اگر SDK به کلید خصوصی API نیاز دارد، بهتر است در Backend استفاده شود. نصب Package در Frontend نباید باعث افشای کلید شود.

آیا استفاده از SDK باعث وابستگی به ارائه‌دهنده می‌شود؟

اگر کلاس‌ها و Typeهای SDK در تمام برنامه پراکنده شوند، بله. با استفاده از Interface و Adapter داخلی می‌توان این وابستگی را محدود کرد.

جمع‌بندی

SDK یک جعبه‌ابزار توسعه است که استفاده از پلتفرم‌ها و سرویس‌های نرم‌افزاری را ساده می‌کند. API قرارداد ارتباط را تعریف می‌کند و SDK همان قرارداد را به توابع، کلاس‌ها و Typeهای قابل‌استفاده در یک زبان برنامه‌نویسی تبدیل می‌کند.

برای استفاده حرفه‌ای از SDK:

1. SDK رسمی و فعال را انتخاب کنید.
2. نسخه وابستگی را کنترل کنید.
3. Client را به‌صورت قابل‌استفاده مجدد بسازید.
4. Timeout و Retry را صریح تنظیم کنید.
5. خطاهای SDK را به خطاهای داخلی تبدیل کنید.
6. کلید API را در Backend نگه دارید.
7. منطق محصول را پشت Interface داخلی قرار دهید.
8. مصرف، هزینه و زمان پاسخ را ثبت کنید.
9. سازگاری قابلیت‌ها را روی مدل واقعی آزمایش کنید.
10. به‌روزرسانی SDK را ابتدا در محیط تست بررسی کنید.

برای اتصال نرم‌افزار Python، TypeScript یا سایر زبان‌ها به مدل‌های هوش مصنوعی، می‌توانید از API سازگار با OpenAI درواره استفاده کنید.

آدرس پایه درواره:

https://api.darvareh.ir/v1

برای دریافت کلید، بررسی مدل‌ها و مشاهده جزئیات فنی به مستندات API درواره مراجعه کنید.

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

مقالات مرتبط

• API چیست و چگونه کار می‌کند؟
• API هوش مصنوعی چیست؟
• راهنمای API سازگار با OpenAI
• مقایسه SDKهای هوش مصنوعی
• ساخت SDK و API Client از OpenAPI
• آموزش HTTP و Status Code
• آموزش اتصال API هوش مصنوعی به نرم‌افزار
• ساخت API آماده Production

منابع

• OpenAI Python SDK
• OpenAI Node.js SDK
• Semantic Versioning 2.0.0
• npm: About Semantic Versioning
• مستندات API درواره

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