آموزش دیجیتال

دسترسی رایگان به هوش مصنوعی Qwen با API هتزنر

تیم MoeinGift1405/06/039 دقیقه مطالعه

اگر حساب فعال هتزنر دارید، اکنون می‌توانید بدون پرداخت هزینه جداگانه برای توکن‌ها، به مدل‌های متن‌باز Qwen از طریق یک API سازگار با استاندارد OpenAI دسترسی پیدا کنید. این قابلیت بخشی از پلتفرم آزمایشی Hetzner Experiments است و به کاربران اجازه می‌دهد مدل‌های میزبانی‌شده روی زیرساخت هتزنر را به ابزارهایی مانند LobeChat، Cherry Studio، OpenCode یا برنامه‌های اختصاصی متصل کنند.

راه‌اندازی این سرویس پیچیده نیست؛ یک توکن می‌سازید، Base URL صحیح را در کلاینت وارد می‌کنید و مدل موردنظر را انتخاب می‌کنید. بااین‌حال، چند نکته مهم وجود دارد: سرویس دائمی و تضمین‌شده نیست، مدل‌های در دسترس ممکن است تغییر کنند و لینک پنل ساخت توکن با آدرس API یکسان نیست.

خلاصه مهم: طبق مستندات رسمی هتزنر، Inference API تا زمانی که در وضعیت آزمایشی قرار دارد رایگان است. در صورت تغییر وضعیت، هتزنر اعلام کرده کاربران را پیشاپیش از طریق ایمیل مطلع خواهد کرد. این سرویس برای پروژه‌های حساس یا محیط Production توصیه نمی‌شود.

Hetzner Inference API چیست؟

Inference API هتزنر یک رابط REST سازگار با OpenAI است که دسترسی به مدل‌های زبانی متن‌باز میزبانی‌شده روی زیرساخت این شرکت را فراهم می‌کند. به زبان ساده، برنامه‌ای که امکان تعریف یک ارائه‌دهنده OpenAI-Compatible و واردکردن Base URL دلخواه را داشته باشد، معمولاً می‌تواند به این سرویس متصل شود.

در زمان نگارش این مطلب، سه Endpoint اصلی در دسترس‌اند:

/v1/models برای مشاهده فهرست مدل‌های فعال؛
/v1/completions برای Completion متنی؛
/v1/chat/completions برای گفت‌وگوهای مبتنی بر پیام.

آدرس پایه رسمی سرویس به شکل زیر است:

https://inference.hetzner.com/api/v1

این آدرس را با صفحه پنل Inference در Hetzner Experiments اشتباه نگیرید. پنل برای ساخت و مدیریت توکن است؛ اما درخواست‌های API باید به دامنه inference.hetzner.com ارسال شوند.

چه مدل‌هایی در دسترس هستند؟

طبق مستندات رسمی هتزنر، فهرست مدل‌ها در دوره آزمایشی ثابت نیست. در زمان تهیه این راهنما، دو مدل زیر در صفحه مستندات دیده می‌شوند:

نام مدل	ساختار	Context	ورودی‌ها
`Qwen/Qwen3.6-35B-A3B-FP8`	MoE؛ مجموع ۳۵ میلیارد و حدود ۳ میلیارد پارامتر فعال	۲۶۲٬۱۴۴ توکن	متن و تصویر
`Qwen3.8-27B`	Dense	۲۶۲٬۱۴۴ توکن	متن و تصویر

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

curl -s https://inference.hetzner.com/api/v1/models \ -H "Authorization: Bearer YOUR_API_TOKEN"

آموزش ساخت توکن Hetzner Inference

وارد حساب کاربری فعال و تأییدشده هتزنر شوید.
به Hetzner Experiments بروید.
از منوی سرویس‌ها بخش Inference را باز کنید.
روی گزینه Create API Token بزنید.
توکن را همان لحظه در یک Password Manager امن ذخیره کنید.

هشدار امنیتی: API Key را داخل تصویر، پیام عمومی، مخزن GitHub یا کد JavaScript سمت مرورگر قرار ندهید. اگر احتمال می‌دهید کلید افشا شده است، آن را از پنل حذف و یک توکن جدید ایجاد کنید.

اتصال به LobeChat، Cherry Studio و کلاینت‌های مشابه

نام گزینه‌ها ممکن است در نسخه‌های مختلف برنامه کمی متفاوت باشد، اما ساختار کلی یکسان است:

وارد بخش Providers یا Model Providers شوید.
یک ارائه‌دهنده Custom یا OpenAI Compatible بسازید.
در قسمت Base URL آدرس https://inference.hetzner.com/api/v1 را وارد کنید.
توکن ساخته‌شده را در بخش API Key قرار دهید.
گزینه Fetch Models، Get Models یا Import Models را بزنید.
مدلی را انتخاب کنید که دقیقاً در پاسخ /models دیده می‌شود.
با یک پیام کوتاه اتصال را آزمایش کنید.

اگر کلاینت به‌صورت خودکار /v1 را به آدرس اضافه می‌کند، مستندات همان کلاینت را بررسی کنید. واردکردن دوباره این بخش می‌تواند آدرسی مانند /api/v1/v1/chat/completions بسازد و خطای 404 ایجاد کند.

تست API با Curl

قبل از تنظیم برنامه‌های گرافیکی، بهتر است اتصال را با یک درخواست ساده آزمایش کنید. دستور زیر را اجرا کنید و مقدار YOUR_API_TOKEN را با توکن خود جایگزین کنید:

curl -s https://inference.hetzner.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen/Qwen3.6-35B-A3B-FP8", "messages": [ {"role": "system", "content": "You are a helpful Persian assistant."}, {"role": "user", "content": "در سه جمله کوتاه خودت را معرفی کن."} ] }'

در ویندوز PowerShell ممکن است شیوه کوتیشن‌گذاری متفاوت باشد. اگر دستور Curl به دلیل کوتیشن خطا داد، از یک کلاینت گرافیکی یا نمونه Python بخش بعد استفاده کنید.

استفاده با Python و کتابخانه OpenAI

از آنجا که API با استاندارد OpenAI سازگار است، می‌توان از SDK رسمی OpenAI برای ارسال درخواست استفاده کرد. ابتدا کتابخانه را نصب کنید:

pip install openai

سپس کلاینت را با Base URL هتزنر مقداردهی کنید:

import os from openai import OpenAI client = OpenAI( base_url="https://inference.hetzner.com/api/v1", api_key=os.environ["HETZNER_INFERENCE_API_KEY"], ) response = client.chat.completions.create( model="Qwen/Qwen3.6-35B-A3B-FP8", messages=[ {"role": "system", "content": "You are a helpful Persian assistant."}, {"role": "user", "content": "یک برنامه هفتگی کوتاه برای یادگیری پایتون بنویس."}, ], ) print(response.choices[0].message.content)

قرار دادن کلید در متغیر محیطی از نوشتن مستقیم آن داخل کد امن‌تر است. همچنین فایل‌های حاوی متغیرهای محرمانه مانند .env را به Git اضافه نکنید.

آیا برای استفاده حتماً باید سرور هتزنر داشته باشیم؟

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

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

رایگان‌بودن سرویس چه محدودیت‌هایی دارد؟

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

بازه زمانی	توکن ورودی	توکن خروجی	تعداد درخواست
۶۰ ثانیه	۴ میلیون	۱۰۰ هزار	۱۰ درخواست

عبور از محدودیت‌ها با خطای HTTP 429 پاسخ داده می‌شود. این اعداد ممکن است در طول آزمایش تغییر کنند؛ بنابراین برای اطلاعات قطعی همیشه مستندات رسمی را دوباره بررسی کنید.

مزایای استفاده از Qwen روی هتزنر

هزینه آزمایشی صفر: تا زمانی که سرویس در وضعیت Experiment قرار دارد، هزینه جداگانه‌ای بابت مصرف API دریافت نمی‌شود.
سازگاری با OpenAI: اتصال به بسیاری از SDKها و کلاینت‌های موجود ساده‌تر است.
عدم نیاز به GPU محلی: پردازش مدل روی زیرساخت هتزنر انجام می‌شود.
Context طولانی: مدل‌های فهرست‌شده در مستندات فعلی Context برابر ۲۶۲٬۱۴۴ توکن دارند.
ورودی تصویر: هر دو مدل فعلی در مستندات با قابلیت متن و تصویر معرفی شده‌اند.
زیرساخت اروپایی: هتزنر این آزمایش را روی زیرساخت خود اجرا می‌کند.

محدودیت‌ها و ریسک‌هایی که باید بدانید

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

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

رفع خطاهای رایج Hetzner Inference API

خطای 401 Unauthorized

توکن اشتباه، منقضی یا حذف شده است. مطمئن شوید هدر درخواست دقیقاً به شکل Authorization: Bearer TOKEN ارسال می‌شود و قبل یا بعد از توکن فاصله اضافه وجود ندارد.

خطای 404 Not Found

معمولاً Base URL اشتباه است یا کلاینت بخش /v1 را دوباره اضافه کرده است. آدرس نهایی Chat Completion باید به https://inference.hetzner.com/api/v1/chat/completions برسد.

خطای 429 Too Many Requests

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

خطای Model Not Found

نام مدل را دستی حدس نزنید. Endpoint مدل‌ها را فراخوانی و شناسه را بدون تغییر کپی کنید. تفاوت حروف بزرگ و کوچک یا حذف بخش Qwen/ می‌تواند باعث خطا شود.

خطاهای 500، 502 یا 503

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

مدل دوم پاسخ نمی‌دهد

در یک سرویس آزمایشی ممکن است یک مدل موقتاً در دسترس نباشد. ابتدا /models را بررسی کنید. اگر مدل در فهرست بود ولی خطا ادامه داشت، با Qwen3.6 تست کنید و گزارش دقیق شامل زمان، Status Code و Request ID را برای پشتیبانی هتزنر بفرستید؛ هرگز API Key را داخل گزارش قرار ندهید.

آیا این API برای استفاده واقعی مناسب است؟

برای آزمایش ابزارهای هوش مصنوعی، ساخت نمونه اولیه، گفت‌وگوی شخصی، بررسی قابلیت Vision یا اتصال یک کلاینت OpenAI-Compatible، این سرویس فرصت ارزشمندی است. اما برای فروشگاه، سامانه پشتیبانی مشتری، پردازش حقوقی، خدمات پزشکی یا هر فرایندی که قطعی‌بودن سرویس اهمیت دارد، نباید تنها ارائه‌دهنده شما باشد.

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

سؤالات متداول

آیا API هوش مصنوعی هتزنر واقعاً رایگان است؟

بله، طبق مستندات رسمی تا زمانی که Inference API در وضعیت آزمایشی قرار دارد رایگان است. هتزنر اعلام کرده تغییر این وضعیت را پیشاپیش از طریق ایمیل اطلاع می‌دهد.

Base URL صحیح هتزنر چیست؟

آدرس رسمی https://inference.hetzner.com/api/v1 است. آدرس experiments.hetzner.com برای ورود به پنل و ساخت توکن استفاده می‌شود.

کدام مدل Qwen پایدارتر است؟

تجربه کاربران ممکن است متفاوت باشد و وضعیت مدل‌ها لحظه‌ای تغییر کند. برای مشاهده گزینه‌های واقعاً فعال، Endpoint /v1/models مرجع قطعی است. در زمان نگارش، Qwen3.6 و Qwen3.8 در مستندات دیده می‌شوند.

آیا می‌توان API را به Cherry Studio یا LobeChat متصل کرد؟

اگر نسخه کلاینت شما از Provider سفارشی یا OpenAI-Compatible پشتیبانی کند، بله. Base URL، API Key و شناسه دقیق مدل را وارد کنید.

آیا هتزنر متن درخواست‌های ما را ذخیره می‌کند؟

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

آیا استفاده از این سرویس به سرور GPU نیاز دارد؟

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

جمع‌بندی

Hetzner Inference API راهی ساده و فعلاً رایگان برای تجربه مدل‌های Qwen از طریق یک رابط سازگار با OpenAI است. با یک حساب معتبر هتزنر و توکن Experiments می‌توانید آن را به کلاینت‌های آماده یا برنامه Python متصل کنید و بدون تهیه GPU محلی، از قابلیت‌های متن و تصویر مدل‌ها بهره ببرید.

مهم‌ترین نکته این است که سرویس را با یک محصول پایدار و دائمی اشتباه نگیرید. مدل‌ها و محدودیت‌ها را از /v1/models و مستندات رسمی بررسی کنید، API Key را امن نگه دارید، برای اختلال‌ها Provider جایگزین داشته باشید و از سرویس برای پردازش داده‌های بسیار حساس یا سامانه‌های حیاتی استفاده نکنید.