آموزش OpenAI SDK با Base URL سفارشی

هدف این راهنما و نیت جست‌وجو

این راهنما نشان می‌دهد چگونه یک SDK سازگار با OpenAI را به Provider دیگری متصل کنید، بدون اینکه کلید یا Base URL داخل کد ذخیره شود. «سازگار» به معنی یکسان‌بودن کامل همه قابلیت‌ها نیست؛ مدل‌ها، Tool Calling، Embedding، Streaming و پیام‌های خطا ممکن است تفاوت داشته باشند.

Providerهای سازگار ثبت‌شده

مراحل ثبت‌نام و آماده‌سازی

1. از Catalog یک Provider با openai_compatible=true انتخاب کنید.
2. در مستندات رسمی همان Provider ثبت‌نام و یک API key محدود ایجاد کنید.
3. Base URL و شناسه مدل را دقیقاً از مستندات یا Dashboard حساب کپی کنید.
4. کلید را در LLM_API_KEY و تنظیمات غیرحساس را در متغیرهای محیطی قرار دهید.
5. قبل از فعال‌کردن Streaming یا Tool Calling، یک درخواست ساده و قابل تکرار اجرا کنید.

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

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],
    base_url=os.environ.get("LLM_BASE_URL", "https://apihub.agnes-ai.com/v1"),
    timeout=30.0,
    max_retries=2,
)

response = client.chat.completions.create(
    model=os.environ.get("LLM_MODEL", "agnes-2.0-flash"),
    messages=[{"role": "user", "content": "سلام!"}],
    max_tokens=64,
)
print(response.choices[0].message.content)

نمونه اولین درخواست با JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: process.env.LLM_BASE_URL ?? "https://apihub.agnes-ai.com/v1",
  timeout: 30_000,
  maxRetries: 2,
});

const response = await client.chat.completions.create({
  model: process.env.LLM_MODEL ?? "agnes-2.0-flash",
  messages: [{ role: "user", content: "سلام!" }],
  max_tokens: 64,
});
console.log(response.choices[0].message.content);

سهمیه و محدودیت‌ها

Retry خودکار نباید Rate Limit را تشدید کند. RPM، TPM، Context، مدل‌های مجاز و هزینه خروج از سهمیه رایگان را از صفحه Provider بررسی کنید. Timeout و تعداد Retry را محدود نگه دارید و برای 429 از Backoff همراه با Jitter استفاده کنید.

وضعیت ایران و شواهد دسترسی

سازگاری OpenAI مستقل از وضعیت ایران است. قبل از استفاده، Evidence ثبت‌نام، دسترسی شبکه و درخواست واقعی مدل را در صفحه Provider بخوانید. استفاده از Base URL جایگزین نباید برای دورزدن Terms، محدودیت کشور یا احراز هویت به کار رود.

خطاهای رایج و رفع اشکال

• 401: نام متغیر محیطی، کلید و Header را بررسی کنید.
• 404: معمولاً Base URL فاقد نسخه API است یا شناسه مدل اشتباه است.
• 422/400: Provider بخشی از Schema یا پارامترهای SDK را پشتیبانی نمی‌کند؛ درخواست را به حداقل کاهش دهید.
• 429: Retry بی‌نهایت نکنید؛ Headerهای Rate Limit و سیاست Provider را بخوانید.
• Streaming یا Tool Calling ناقص: سازگاری Chat Completion لزوماً این قابلیت‌ها را تضمین نمی‌کند.

چه زمانی این روش مناسب نیست؟

اگر Provider فقط شباهت سطحی به Schema OpenAI دارد، نیاز به API اختصاصی با قابلیت‌های ویژه دارید، یا تفاوت رفتار مدل برای محصول حساس مهم است، Adapter اختصاصی بهتر از تکیه بر سازگاری عمومی SDK است.

منابع رسمی تاریخ‌دار

• Agnes AI — مستندات رسمی — تاریخ بررسی داده: 2026-07-24
• Aion Labs — مستندات رسمی — تاریخ بررسی داده: 2026-07-20
• Cerebras Inference — مستندات رسمی — تاریخ بررسی داده: 2026-07-20
• Cloudflare Workers AI — مستندات رسمی — تاریخ بررسی داده: 2026-07-20
• Fireworks AI — مستندات رسمی — تاریخ بررسی داده: 2026-08-07
• FreeTheAI — مستندات رسمی — تاریخ بررسی داده: 2026-08-05
• GitHub Models — مستندات رسمی — تاریخ بررسی داده: 2026-07-20
• Google Gemini API — مستندات رسمی — تاریخ بررسی داده: 2026-07-20
• Groq — مستندات رسمی — تاریخ بررسی داده: 2026-07-20
• Hugging Face Inference Providers — مستندات رسمی — تاریخ بررسی داده: 2026-07-24
• Jina AI — مستندات رسمی — تاریخ بررسی داده: 2026-08-05
• Kilo Gateway — مستندات رسمی — تاریخ بررسی داده: 2026-07-24
• LLM7.io — مستندات رسمی — تاریخ بررسی داده: 2026-08-05
• Mistral AI — مستندات رسمی — تاریخ بررسی داده: 2026-07-24
• ModelScope (Alibaba) — مستندات رسمی — تاریخ بررسی داده: 2026-08-05
• NVIDIA NIM API Catalog — مستندات رسمی — تاریخ بررسی داده: 2026-07-21
• OpenCode Zen — مستندات رسمی — تاریخ بررسی داده: 2026-08-05
• OpenRouter — مستندات رسمی — تاریخ بررسی داده: 2026-07-20
• OVHcloud AI Endpoints — مستندات رسمی — تاریخ بررسی داده: 2026-07-24
• Pinecone Inference — مستندات رسمی — تاریخ بررسی داده: 2026-08-05
• SambaNova Cloud — مستندات رسمی — تاریخ بررسی داده: 2026-07-24
• SiliconFlow — مستندات رسمی — تاریخ بررسی داده: 2026-07-20
• Vercel AI Gateway — مستندات رسمی — تاریخ بررسی داده: 2026-07-21
• Weaviate Embeddings — مستندات رسمی — تاریخ بررسی داده: 2026-08-05
• Z.AI — مستندات رسمی — تاریخ بررسی داده: 2026-08-05

مطالب مرتبط و پیوندهای داخلی

• Providerهای سازگار بدون روش پرداخت ثبت‌شده
• APIهای مناسب Coding و Tool Calling
• تفاوت انواع سهمیه رایگان
• Catalog کامل Providerها
• نمونه استفاده‌شده در کد: Agnes AI