۱۴۰۵ آبان ۲۶, سه‌شنبه
دلار آمریکا۲۶۶٬۸۹۵▼ ۰٫۶۸٪یورو۲۹۴٬۳۶۰▼ ۰٫۶۹٪درهم امارات۷۲٬۷۲۵▼ ۰٫۶۸٪سکه امامی۲۵۱٬۴۹۰٬۰۰۰▲ ۰٫۳۷٪طلای ۱۸ عیار (گرم)۲۴٬۶۶۶٬۶۰۰▲ ۰٫۴٪انس طلا۳٬۸۷۰ $▲ ۰٫۱۴٪تتر۲۶۹٬۵۴۰▲ ۰٫۰۵٪بیت‌کوین۶۴٬۲۰۰ $▼ ۱٫۵۶٪اتریوم۱٬۷۸۷ $▼ ۲٫۰۸٪سولانا۷۲٫۵۵ $▲ ۱٫۴۷٪اپل۳۵۱٫۶۹ $▼ ۰٫۳۱٪انویدیا۱۵۴٫۹۴ $▼ ۰٫۷۷٪مایکروسافت۴۹۹٫۶۵ $▼ ۳٫۵۴٪آلفابت (گوگل)۲۸۰٫۴۰ $▼ ۱٫۱۷٪تسلا۳۷۹٫۶۲ $▼ ۰٫۰۳٪شاخص نزدک۲۴٬۲۴۶ $▼ ۱٫۰۸٪
نرخ ارز

وب‌سرویس سازگار با OpenAI در سرور ایرانی؛ پایتون و Node.js

آموزش عملی اتصال به وب‌سرویس سازگار با OpenAI از سرور ایرانی: base URL و کلید، پایتون و Node.js، streaming، تلاش دوباره، خطای 401 و 429 و امنیت کلید.

کاور گرافیکی DevNA با پنجره‌ی کد که یک کلاینت OpenAI را با base_url سفارشی نشان می‌دهد
کاور گرافیکی DevNA با پنجره‌ی کد که یک کلاینت OpenAI را با base_url سفارشی نشان می‌دهد
فهرست مطالب
  1. «سازگار با OpenAI» یعنی چه؟
  2. نمونه‌ی ما: گیسو و دو نشانی
  3. آماده‌سازی: کلید و متغیر محیطی
  4. اولین درخواست با curl
  5. انتخاب شناسه‌ی مدل با /models
  6. پایتون با SDK رسمی
  7. اتصال با Node.js و SDK رسمی
  8. خروجی جریانی (Streaming)؛ پاسخ را همان لحظه بگیرید
  9. زمان انتظار و تلاش دوباره
  10. مدیریت خطا: 401، 429 و بقیه
  11. امنیت کلید
  12. اگر وصل نشد
  13. مطالب مرتبط

شفاف‌سازی: گیسو در این آموزش نمونه‌ی عملی است و به مجموعه‌ای تعلق دارد که DevNA را منتشر می‌کند. نشانی‌ها، مسیرها و نمونه‌کدها بر پایه‌ی مستندات رسمی گیسو نوشته شده‌اند و روش کار برای هر وب‌سرویس سازگار با OpenAI یکسان است.

اگر سرورتان در یک دیتاسنتر ایرانی است و می‌خواهید از آن یک مدل زبانی صدا بزنید، خبر خوب این است که لازم نیست چیز تازه‌ای یاد بگیرید. بیشتر وب‌سرویس‌های امروزی قالب API شرکت OpenAI را پذیرفته‌اند و به همین دلیل یک وب‌سرویس سازگار با OpenAI را با همان ابزار همیشگی صدا می‌زنید: همان کیت توسعه‌ی (SDK) رسمی را برمی‌دارید، نشانی را عوض می‌کنید و کار می‌کند. در این مطلب از صفر تا کد آماده‌ی تولید می‌رویم: متغیر محیطی، پایتون، Node.js، streaming، تلاش دوباره، مدیریت خطا و نگهداری درست کلید.

«سازگار با OpenAI» یعنی چه؟

یعنی وب‌سرویس همان مسیرهایی را دارد که OpenAI دارد، مثل /chat/completions و /models، همان قالب JSON را می‌پذیرد و پاسخ را هم در همان شکل برمی‌گرداند. نتیجه‌اش این است که کتابخانه‌های رسمی (openai-python و openai-node) بدون تغییر کار می‌کنند.

برای وصل شدن به چنین سرویسی فقط دو چیز لازم دارید:

  • نشانی پایه (base_url): نشانی پایه‌ی API که جای نشانی پیش‌فرض OpenAI می‌نشیند.
  • کلید API: رشته‌ای که در هدر Authorization: Bearer ... فرستاده می‌شود. SDK این هدر را خودش می‌سازد.

نام مدل هم همان پارامتر model است، اما شناسه‌ها را هر سرویس خودش تعیین می‌کند. پس هیچ‌وقت شناسه را از حافظه ننویسید و از خود سرویس بپرسید؛ در بخش /models همین را انجام می‌دهیم.

نمونه‌ی ما: گیسو و دو نشانی

برای مثال از گیسو استفاده می‌کنیم. مستندات وب‌سرویس گیسو نشانی پایه‌ی https://gisoo.pro/api/v1 را معرفی می‌کند و برای سرورهای ایران یک نشانی ویژه‌ی سرورهای ایران هم دارد: https://ir.gisoo.pro/api/v1. طبق همان مستندات، تفاوت دو نشانی فقط در همین دامنه است و کلید، اعتبار، مدل‌ها و مسیرها یکی می‌مانند. ما در همه‌ی نمونه‌ها نشانی ایران را به کار می‌بریم.

نکته‌ی مهم برای سرور ایرانی این است که برنامه‌ی شما فقط به همین یک نشانی وصل می‌شود و اتصال به سرویس‌دهنده‌ی مدل از سمت گیسو انجام می‌شود. بنابراین روی سرور شما پراکسی یا تونل لازم نیست و ما هم چنین چیزی را توصیه نمی‌کنیم.

آماده‌سازی: کلید و متغیر محیطی

کلید را از پنل سرویس می‌گیرید. در گیسو کلید با sk-gisoo-v1- شروع می‌شود و فقط یک بار کامل نشان داده می‌شود؛ پس همان لحظه جای امنی بگذاریدش. بعد آن را در متغیر محیطی قرار دهید، نه در کد:

# Linux / macOS
export GISOO_API_KEY="sk-gisoo-v1-..."
export OPENAI_BASE_URL="https://ir.gisoo.pro/api/v1"

در PowerShell هم معادلش $env:GISOO_API_KEY = "..." است. اگر برنامه‌تان با systemd یا Docker اجرا می‌شود، متغیر را در فایل .env بیرون از ریپو یا در بخش secret همان ابزار تعریف کنید.

اولین درخواست با curl

قبل از نوشتن کد، اتصال را با curl بیازمایید تا مطمئن شوید مشکلی در شبکه‌ی سرور نیست. مستندات گیسو پیشنهاد می‌کند این دستور را روی خود سرور اجرا کنید، نه روی لپ‌تاپ:

curl -sS -o /dev/null -w "HTTP %{http_code} in %{time_total}s\n" \
  https://ir.gisoo.pro/api/v1/models

خروجی HTTP 200 یعنی سرور شما به نشانی می‌رسد و این دستور کلید لازم ندارد. حالا یک درخواست واقعی بفرستید:

curl https://ir.gisoo.pro/api/v1/chat/completions \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Answer in Persian, in two sentences."},
      {"role": "user", "content": "What is an API key?"}
    ]
  }'

متن پاسخ در choices[0].message.content است و مصرف توکن در usage می‌آید.

انتخاب شناسه‌ی مدل با /models

شناسه‌ی مدل‌ها ثابت نیستند و سرویس‌ها مدل اضافه یا حذف می‌کنند. بهترین کار این است که فهرست را خودتان بگیرید:

curl -sS https://ir.gisoo.pro/api/v1/models

یا با SDK پایتون:

for m in client.models.list():
    print(m.id)

در گیسو بعضی مدل‌ها با نام خودشان صدا زده می‌شوند، مثل gpt-4o-mini، و بعضی با پیشوند openrouter/، مثل openrouter/anthropic/claude-sonnet-4.5. هر شناسه‌ای را که از فهرست برداشتید عیناً در model بگذارید. اگر شناسه اشتباه باشد، خطای 404 model_not_found می‌گیرید.

پایتون با SDK رسمی

نصب با pip install openai. کد زیر همان نمونه‌ی مستندات است، فقط با نشانی ایران:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ir.gisoo.pro/api/v1",
    api_key=os.environ["GISOO_API_KEY"],
    timeout=120,
    max_retries=3,
)

reply = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Answer in Persian, in two sentences."},
        {"role": "user", "content": "What is an API key?"},
    ],
)
print(reply.choices[0].message.content)
print(reply.usage)

دو پارامتر timeout و max_retries را در بخش بعد توضیح می‌دهیم.

اتصال با Node.js و SDK رسمی

نصب با npm install openai. اینجا هم نام گزینه‌ها کمی فرق دارد (baseURL و apiKey):

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ir.gisoo.pro/api/v1",
  apiKey: process.env.GISOO_API_KEY,
  timeout: 120_000,
  maxRetries: 3,
});

const reply = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "system", content: "Answer in Persian, in two sentences." },
    { role: "user", content: "What is an API key?" },
  ],
});
console.log(reply.choices[0].message.content);

فایل را با پسوند .mjs ذخیره کنید یا در package.json مقدار "type": "module" بگذارید تا import و await سطح بالا کار کند.

خروجی جریانی (Streaming)؛ پاسخ را همان لحظه بگیرید

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

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Explain REST in three sentences."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Explain REST in three sentences." }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

اگر جلوی برنامه‌ی خودتان nginx گذاشته‌اید، برای همان مسیر proxy_buffering off را تنظیم کنید؛ وگرنه nginx تکه‌ها را نگه می‌دارد و یک‌جا می‌فرستد.

زمان انتظار و تلاش دوباره

مستندات گیسو می‌گوید خودش تا حدود ۹۰ ثانیه برای پاسخ سرویس‌دهنده‌ی مدل صبر می‌کند. پس زمان انتظار کلاینت شما باید بیشتر از آن باشد؛ ما ۱۲۰ ثانیه گذاشتیم تا درخواست را زودتر از سرویس رها نکنید.

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

مدیریت خطا: 401، 429 و بقیه

کد وضعیت را بخوانید و بر اساسش تصمیم بگیرید. جدول زیر از مستندات گیسو آمده است:

وضعیت معنی کار درست
401 missing_api_key کلید در هدر نبود متغیر محیطی را در همان پردازش بررسی کنید
401 invalid_api_key کلید نادرست است دوباره و کامل کپی کنید؛ فاصله یا خط تازه نماند
402 insufficient_credit اعتبار کافی نیست حساب را شارژ کنید
404 model_not_found شناسه‌ی مدل اشتباه است از /models بردارید
429 rate_limit_exceeded سقف درخواست در دقیقه پر شد صبر کنید و دوباره بفرستید

سقف پیش‌فرض حساب در گیسو ۶۰ درخواست در دقیقه است و می‌شود برای هر کلید سقف جدا گذاشت. در کد، خطاها را این‌طور بگیرید:

import openai

try:
    reply = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello"}],
    )
except openai.AuthenticationError:
    # 401: the key is wrong, expired or revoked. Retrying will not help.
    raise
except openai.RateLimitError:
    # 429 after the SDK's own retries: slow down or queue the request.
    ...
except openai.APIConnectionError:
    # network problem between your server and the API
    ...
except openai.APIStatusError as e:
    print(e.status_code, e.response.headers.get("x-request-id"))
try {
  const reply = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    console.error(err.status, err.message);
    // 401: fix the key. 429: slow down. 5xx: SDK already retried.
  } else {
    throw err;
  }
}

شناسه‌ی درخواست (هدر X-Request-Id) را در لاگ نگه دارید. اگر لازم شد با پشتیبانی تماس بگیرید، همین شناسه بررسی را سریع می‌کند.

امنیت کلید

کلید API مثل رمز عبور است و هر کس آن را داشته باشد از اعتبار شما خرج می‌کند. چند قاعده‌ی ساده:

  1. کلید را هرگز در کد فرانت‌اند، اپ موبایل یا هر فایلی که همراه برنامه منتشر می‌شود نگذارید. هر کسی صفحه را باز کند می‌بیندش. مرورگر باید با سرور خودتان حرف بزند و فقط سرور کلید را بداند. اگر برای ورود کاربران بین JWT و سشن مردد هستید، آن مقایسه را هم ببینید.
  2. کلید را وارد گیت نکنید. .env را در .gitignore بگذارید و اگر یک بار commit شد، آن را لورفته بدانید و باطلش کنید.
  3. برای هر برنامه و هر محیط (توسعه و تولید) یک کلید جدا بسازید.
  4. برای هر کلید سقف هزینه بگذارید. اگر لو برود، فقط تا همان سقف خرج می‌شود.
  5. اگر سرورتان IP ثابت دارد، آن را در فهرست IP مجاز کلید ثبت کنید. در کد هم فقط با نام دامنه وصل شوید، نه با IP.
  6. اگر کلید لو رفت، اول باطلش کنید و بعد دنبال منشأ نشت بگردید.

یک نمونه‌ی ساده‌ی سرور که کلید را پیش خودش نگه می‌دارد، با Express:

import express from "express";
import OpenAI from "openai";

const app = express();
app.use(express.json());
const ai = new OpenAI({ baseURL: "https://ir.gisoo.pro/api/v1", apiKey: process.env.GISOO_API_KEY });

app.post("/chat", async (req, res) => {
  try {
    const reply = await ai.chat.completions.create({
      model: "gpt-4o-mini",
      messages: [{ role: "user", content: String(req.body.message).slice(0, 4000) }],
      max_tokens: 400,
    });
    res.json({ text: reply.choices[0].message.content });
  } catch (err) {
    console.error(err);
    res.status(502).json({ error: "upstream_error" });
  }
});
app.listen(3000);

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

اگر وصل نشد

هر درخواستی که به سرور سرویس برسد پاسخ HTTP می‌گیرد، حتی وقتی رد شود. پس خطایی که هیچ پاسخی ندارد یعنی درخواست در مسیر شبکه یا روی خود سرور شما مانده است. مستندات گیسو چند کد curl را توضیح داده؛ مهم‌ترین‌ها:

  • کد 6: نام دامنه پیدا نشد؛ DNS سرور را بررسی کنید.
  • کد 7: اتصال برقرار نشد؛ فایروال باید خروجی پورت 443 را باز بگذارد.
  • کد 28: زمان انتظار تمام شد؛ مسیر خروجی سرور یا دیتاسنتر را بررسی کنید.
  • کد 60: گواهی تأیید نشد؛ بسته‌ی ca-certificates را به‌روز کنید و بررسی گواهی را خاموش نکنید.

هیچ سرویسی نمی‌تواند وصل بودن از همه‌ی شبکه‌ها را تضمین کند؛ گیسو هم در مستندات خودش چنین قولی نمی‌دهد. به همین دلیل، آزمایش با curl را بخشی از آماده‌سازی سرور بدانید.

مطالب مرتبط

اگر می‌خواهید مدل را روی سرور خودتان اجرا کنید، راهنمای اجرای مدل زبانی محلی با Ollama و برای آشنایی با خود مفهوم، مدل زبانی بزرگ (LLM) چیست؟ را بخوانید. مدل‌های تازه و راه استفاده از آن‌ها در ایران هم در این رپورتاژ آمده است.

$ devna rate --article

—
هنوز رأیی ثبت نشده
  1. ۵۰
  2. ۴۰
  3. ۳۰
  4. ۲۰
  5. ۱۰

این مطلب چقدر به کارتان آمد؟

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

واکنش شما

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

پرسش‌های پرتکرار

سازگار با OpenAI یعنی چه؟

یعنی وب‌سرویس همان مسیرها، قالب درخواست و قالب پاسخ API شرکت OpenAI را دارد. برای اتصال معمولاً فقط base URL و کلید را در SDK رسمی عوض می‌کنید.

برای سرور داخل ایران کدام نشانی را بگذارم؟

طبق مستندات گیسو، برای سرورهای دیتاسنترهای ایرانی نشانی https://ir.gisoo.pro/api/v1 پیشنهاد شده است. کلید، اعتبار، مدل‌ها و مسیرها با نشانی اصلی یکی‌اند.

اگر کلید در گیت یا فرانت‌اند لو رفت چه کنم؟

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

چرا به‌جای 429 باید دوباره تلاش کنم و برای 401 نه؟

429 یعنی سقف درخواست پر شده و کمی بعد برطرف می‌شود. 401 یعنی خود کلید مشکل دارد و تکرار درخواست چیزی را درست نمی‌کند.

خطایی در این مطلب دیدید؟ به تحریریه گزارش دهید؛ اصلاحیه‌ها طبق اصول تحریریه ثبت می‌شوند.

دیدگاه‌ها

۰/۲٬۰۰۰

دیدگاه‌ها پس از بررسی تحریریه منتشر می‌شوند. توهین، تبلیغ و لینک‌های بی‌ربط حذف می‌شوند؛ نقد فنی و مستند همیشه خوش‌آمد است.

$ comments --count۰

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

مطالب مرتبط