آموزش جامع OpenRouter API: دروازه‌ای به مدل‌های هوش مصنوعی

آموزش جامع OpenRouter API: دروازه‌ای به مدل‌های هوش مصنوعی پیشرفته

در دنیای پرشتاب هوش مصنوعی، دسترسی به مدل‌های زبانی بزرگ (LLMs) و مدل‌های چندوجهی (Multimodal Models) متنوع، برای توسعه‌دهندگان و خالقان محتوا، از اهمیت بالایی برخوردار است. OpenRouter API پلتفرمی قدرتمند است که این دسترسی را به شکلی یکپارچه و کارآمد فراهم می‌کند. این آموزش جامع، شما را با تمام جنبه‌های OpenRouter API آشنا کرده و نحوه استفاده از آن را برای پروژه‌های خود، گام به گام توضیح می‌دهد.

مقدمه

OpenRouter یک API واحد برای دسترسی به طیف وسیعی از مدل‌های هوش مصنوعی، از جمله GPT-3.5، GPT-4، Claude، Llama، و بسیاری دیگر است. این پلتفرم با هدف ساده‌سازی فرآیند ادغام مدل‌های هوش مصنوعی در برنامه‌ها و خدمات مختلف طراحی شده است. به جای نیاز به مدیریت چندین API و کلیدهای مختلف، OpenRouter یک نقطه ورود واحد ارائه می‌دهد که به شما امکان می‌دهد با حداقل کدنویسی، از قدرت مدل‌های پیشرفته بهره‌مند شوید.

مزایای استفاده از OpenRouter API عبارتند از:

• دسترسی گسترده: به بیش از ۱۰۰ مدل هوش مصنوعی از ارائه‌دهندگان مختلف دسترسی پیدا کنید.
• یکپارچگی آسان: با یک API واحد، از پیچیدگی‌های مرتبط با مدیریت چندین API جلوگیری کنید.
• هزینه بهینه: OpenRouter اغلب قیمت‌های رقابتی‌تری نسبت به دسترسی مستقیم به برخی از مدل‌ها ارائه می‌دهد و به شما کمک می‌کند تا هزینه‌های خود را مدیریت کنید. برای اطلاعات بیشتر در مورد قیمت‌گذاری، به صفحه قیمت‌گذاری Axeto مراجعه کنید.
• انعطاف‌پذیری: به راحتی مدل‌ها را تغییر دهید و بهترین مدل را برای نیازهای خاص خود انتخاب کنید.
• مدیریت کلیدهای API: OpenRouter به شما امکان می‌دهد کلیدهای API خود را به صورت متمرکز مدیریت کنید.

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

پیش‌نیازها

قبل از شروع، اطمینان حاصل کنید که پیش‌نیازهای زیر را برآورده کرده‌اید:

1. حساب OpenRouter: برای استفاده از OpenRouter API، ابتدا باید در وب‌سایت OpenRouter یک حساب کاربری ایجاد کنید. این فرآیند ساده و رایگان است.

2. کلید API: پس از ایجاد حساب کاربری، باید یک کلید API از داشبورد OpenRouter خود تولید کنید. این کلید برای احراز هویت درخواست‌های شما به API ضروری است. آن را در مکانی امن نگهداری کرده و هرگز آن را در کد منبع عمومی خود قرار ندهید.

3. محیط برنامه‌نویسی: یک محیط برنامه‌نویسی آماده (مانند Python، Node.js، Go، یا هر زبان دیگری که با آن راحت هستید) نیاز دارید. در این آموزش، ما از پایتون برای مثال‌های کد استفاده خواهیم کرد، اما مفاهیم قابل تعمیم به سایر زبان‌ها هستند.

4. نصب کتابخانه‌های لازم: برای پایتون، کتابخانه requests برای ارسال درخواست‌های HTTP مورد نیاز است. می‌توانید آن را با دستور pip install requests نصب کنید.

5. آشنایی با JSON: OpenRouter API داده‌ها را در قالب JSON ارسال و دریافت می‌کند، بنابراین آشنایی با ساختار JSON مفید خواهد بود.

با فراهم کردن این پیش‌نیازها، شما آماده‌اید تا سفر خود را در دنیای OpenRouter API آغاز کنید!

گام ۱: دریافت کلید API و تنظیم محیط

اولین قدم برای استفاده از OpenRouter API، دریافت کلید API و تنظیم محیط توسعه شماست.

1. ثبت‌نام در OpenRouter:

* به وب‌سایت OpenRouter مراجعه کنید.

* روی دکمه "Sign Up" یا "Get Started" کلیک کنید.

* فرآیند ثبت‌نام را با استفاده از ایمیل یا حساب‌های اجتماعی خود تکمیل کنید.

2. تولید کلید API:

* پس از ورود به حساب کاربری خود، به داشبورد (Dashboard) بروید.

* معمولاً بخشی با عنوان "API Keys" یا "Settings" وجود دارد.

* روی "Create New Key" یا مشابه آن کلیک کنید.

* یک نام برای کلید خود (مثلاً "My Axeto Project") وارد کنید تا بتوانید آن را در آینده شناسایی کنید.

* کلید API تولید شده را کپی کنید. این کلید فقط یک بار نمایش داده می‌شود، پس حتماً آن را در مکانی امن (مانند یک فایل .env یا مدیر رمز عبور) ذخیره کنید.

3. تنظیم متغیر محیطی (اختیاری اما توصیه شده):

برای امنیت بیشتر و جلوگیری از قرار گرفتن کلید API در کد منبع، توصیه می‌شود آن را به عنوان یک متغیر محیطی تنظیم کنید.

در لینوکس/macOS:

```bash

export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"

```

در ویندوز (Command Prompt):

```cmd

set OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"

```

در ویندوز (PowerShell):

```powershell

$env:OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"

```

یا می‌توانید از یک فایل .env با کتابخانه‌هایی مانند python-dotenv در پایتون استفاده کنید.

4. نصب کتابخانه‌های پایتون:

اگر از پایتون استفاده می‌کنید، کتابخانه requests را نصب کنید:

```bash

pip install requests python-dotenv

```

python-dotenv برای بارگذاری متغیرهای محیطی از فایل .env مفید است.

حالا که کلید API خود را دارید و محیط را تنظیم کرده‌اید، آماده‌اید تا اولین درخواست خود را به OpenRouter API ارسال کنید.

گام ۲: ارسال اولین درخواست به OpenRouter API

در این گام، نحوه ارسال یک درخواست ساده به OpenRouter API برای دریافت پاسخ از یک مدل زبانی را بررسی می‌کنیم. ما از پایتون و کتابخانه requests استفاده خواهیم کرد.

1. ساختار درخواست:

OpenRouter API از ساختار مشابه با OpenAI API برای درخواست‌های تکمیل چت (Chat Completions) استفاده می‌کند. این درخواست‌ها معمولاً شامل موارد زیر هستند:

* URL Endpoint: https://openrouter.ai/api/v1/chat/completions

* Header: شامل Authorization (با کلید API شما) و Content-Type: application/json.

* Body (JSON): شامل model (نام مدل مورد نظر), messages (لیستی از اشیاء پیام‌ها با نقش user, assistant, system), و پارامترهای اختیاری دیگر مانند temperature, max_tokens.

2. مثال کد پایتون:

ابتدا، یک فایل .env در کنار فایل پایتون خود ایجاد کنید و کلید API را در آن قرار دهید:

```

OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"

```

سپس، فایل پایتون خود را (مثلاً openrouter_example.py) ایجاد کنید:

```python

import os

import requests

import json

from dotenv import load_dotenv

# بارگذاری متغیرهای محیطی از فایل .env

load_dotenv()

# دریافت کلید API از متغیر محیطی

OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")

if not OPENROUTER_API_KEY:

raise ValueError("OPENROUTER_API_KEY not found in environment variables or .env file.")

# URL Endpoint برای تکمیل چت

OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions"

# انتخاب مدل (مثال: gpt-3.5-turbo. برای لیست کامل مدل‌ها به مستندات OpenRouter مراجعه کنید)

# می‌توانید مدل‌های دیگر مانند "mistralai/mistral-7b-instruct", "google/gemini-pro" را امتحان کنید.

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

MODEL_NAME = "openai/gpt-3.5-turbo" # یک مدل محبوب و مقرون به صرفه

# پیام‌ها برای ارسال به مدل

messages = [

{"role": "system", "content": "شما یک دستیار هوش مصنوعی مفید و خلاق هستید که به زبان فارسی پاسخ می‌دهید."},

{"role": "user", "content": "معنی لغت 'Axeto' چیست؟"},

{"role": "user", "content": "چند ایده برای تولید محتوا با هوش مصنوعی بدهید."},

{"role": "assistant", "content": "البته! آیا مایلید درباره تولید محتوای متنی، تصویری یا ویدیویی صحبت کنیم؟"},

{"role": "user", "content": "لطفاً چند ایده برای تولید محتوای متنی با هوش مصنوعی برای یک بلاگ فارسی زبان ارائه دهید."}

]

# داده‌های درخواست

payload = {

"model": MODEL_NAME,

"messages": messages,

"temperature": 0.7, # خلاقیت مدل (۰.۰ برای پاسخ‌های قطعی‌تر، ۱.۰ برای خلاقیت بیشتر)

"max_tokens": 500, # حداکثر تعداد توکن‌های تولید شده در پاسخ

# "stream": True, # برای دریافت پاسخ به صورت جریانی (streaming)

}

# هدرهای درخواست

headers = {

"Authorization": f"Bearer {OPENROUTER_API_KEY}",

"Content-Type": "application/json",

# "HTTP-Referer": "https://your-app-url.com", # اختیاری: برای ردیابی استفاده

# "X-Title": "Your App Name", # اختیاری: برای ردیابی استفاده

}

print(f"در حال ارسال درخواست به مدل: {MODEL_NAME}...")

try:

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

response = requests.post(OPENROUTER_API_URL, headers=headers, data=json.dumps(payload))

response.raise_for_status() # بررسی خطاهای HTTP

# استخراج پاسخ

response_data = response.json()

if response_data and "choices" in response_data and len(response_data["choices"]) > 0:

assistant_response = response_data["choices"][0]["message"]["content"]

print("\nپاسخ مدل:")

print(assistant_response)

# برای مشاهده جزئیات بیشتر در مورد پاسخ، می‌توانید کل شیء response_data را پرینت کنید.

# print("\nتمام داده‌های پاسخ:", json.dumps(response_data, indent=2, ensure_ascii=False))

else:

print("پاسخی از مدل دریافت نشد یا فرمت آن نامعتبر است.")

print(json.dumps(response_data, indent=2, ensure_ascii=False))

except requests.exceptions.HTTPError as errh:

print(f"خطای HTTP: {errh}")

print(f"پاسخ سرور: {errh.response.text}")

except requests.exceptions.ConnectionError as errc:

print(f"خطای اتصال: {errc}")

except requests.exceptions.Timeout as errt:

print(f"خطای زمان‌بندی: {errt}")

except requests.exceptions.RequestException as err:

print(f"خطای کلی: {err}")

except json.JSONDecodeError:

print("خطا در تجزیه JSON پاسخ.")

print(f"پاسخ خام: {response.text}")

```

3. اجرای کد:

فایل پایتون را اجرا کنید:

```bash

python openrouter_example.py

```

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

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

گام ۳: کاوش مدل‌ها و پارامترهای پیشرفته

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

1. انتخاب مدل مناسب:

OpenRouter لیست گسترده‌ای از مدل‌ها را ارائه می‌دهد، از مدل‌های متن‌باز (مانند Llama، Mistral) گرفته تا مدل‌های تجاری (مانند GPT، Claude). انتخاب مدل به نیازهای پروژه شما، بودجه، و کیفیت مورد انتظار بستگی دارد.

* لیست مدل‌ها: برای مشاهده لیست کامل و به‌روز مدل‌ها، به صفحه مدل‌های OpenRouter مراجعه کنید.

* مدل‌های پیشنهادی برای فارسی:

* برای کیفیت بالا: openai/gpt-4-turbo, anthropic/claude-3-opus, google/gemini-pro-1.5-flash

* برای تعادل کیفیت و هزینه: openai/gpt-3.5-turbo, mistralai/mistral-large-latest

* برای مدل‌های متن‌باز و مقرون به صرفه: mistralai/mixtral-8x7b-instruct, nousresearch/nous-hermes-2-mixtral-8x7b-dpo

* مدل‌های چندوجهی (Multimodal): برخی مدل‌ها مانند openai/gpt-4o قابلیت پردازش و تولید تصویر را نیز دارند. برای مثال عملی از تولید تصویر، به اینجا مراجعه کنید.

جدول مقایسه مدل‌ها (مثال):

2. پارامترهای پیشرفته:

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

* temperature (نوع: float, پیش‌فرض: 0.7): میزان خلاقیت و تصادفی بودن پاسخ را کنترل می‌کند.

* 0.0: پاسخ‌های قطعی و تکراری‌تر (مناسب برای خلاصه‌سازی، ترجمه).

* 1.0: پاسخ‌های خلاقانه و متنوع‌تر (مناسب برای تولید داستان، ایده‌پردازی).

* max_tokens (نوع: integer, پیش‌فرض: 500 در OpenRouter): حداکثر تعداد توکن‌هایی که مدل می‌تواند در پاسخ تولید کند.

* توجه داشته باشید که هر توکن معادل حدود ۰.۷۵ کلمه انگلیسی است. برای فارسی، این نسبت کمی متفاوت است.

* top_p (نوع: float, پیش‌فرض: 1.0): یک روش جایگزین برای کنترل خلاقیت (sampling). مدل فقط از توکن‌هایی که مجموع احتمالشان به top_p می‌رسد، انتخاب می‌کند.

* معمولاً از temperature یا top_p استفاده می‌شود، نه هر دو به طور همزمان.

* frequency_penalty (نوع: float, پیش‌فرض: 0.0): میزان جریمه برای تکرار کلمات در پاسخ.

* مقادیر مثبت باعث کاهش تکرار کلمات می‌شود.

* presence_penalty (نوع: float, پیش‌فرض: 0.0): میزان جریمه برای تکرار مفاهیم در پاسخ.

* مقادیر مثبت باعث تشویق مدل به صحبت درباره موضوعات جدید می‌شود.

* seed (نوع: integer, اختیاری): برای بازتولیدپذیری پاسخ‌ها. اگر یک seed مشخص کنید، مدل با همان ورودی، تقریباً همیشه پاسخ یکسانی تولید خواهد کرد.

* stream (نوع: boolean, پیش‌فرض: False): اگر True باشد، پاسخ به صورت جریانی (مانند تایپ شدن) دریافت می‌شود که برای رابط‌های کاربری بلادرنگ مفید است.

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

```python

import os

import requests

import json

from dotenv import load_dotenv

load_dotenv()

OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")

OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions"

if not OPENROUTER_API_KEY:

raise ValueError("OPENROUTER_API_KEY not found.")

def get_completion(model_name, messages, temperature=0.7, max_tokens=500, stream=False):

payload = {

"model": model_name,

"messages": messages,

"temperature": temperature,

"max_tokens": max_tokens,

"stream": stream,

# "top_p": 1.0,

# "frequency_penalty": 0.0,

# "presence_penalty": 0.0,

# "seed": 42, # برای بازتولیدپذیری

}

headers = {

"Authorization": f"Bearer {OPENROUTER_API_KEY}",

"Content-Type": "application/json",

"HTTP-Referer": "https://axeto.ai", # برای ردیابی Axeto

"X-Title": "Axeto OpenRouter Tutorial", # برای ردیابی Axeto

}

print(f"\nدر حال ارسال درخواست به مدل: {model_name} با temperature={temperature}, max_tokens={max_tokens}...")

try:

response = requests.post(OPENROUTER_API_URL, headers=headers, data=json.dumps(payload), stream=stream)

response.raise_for_status()

if stream:

print("پاسخ جریانی:")

for chunk in response.iter_lines():

if chunk:

try:

# OpenRouter stream format is a bit different, often starts with "data: "

decoded_chunk = chunk.decode('utf-8')

if decoded_chunk.startswith("data: "):

json_data = decoded_chunk[len("data: "):]

if json_data == "[DONE]":

break

chunk_data = json.loads(json_data)

if "choices" in chunk_data and len(chunk_data["choices"]) > 0:

delta = chunk_data["choices"][0]["delta"]

if "content" in delta:

print(delta["content"], end="", flush=True)

except json.JSONDecodeError:

# print(f"Could not decode JSON from chunk: {decoded_chunk}")

pass

print("\n") # Newline after streamed response

else:

response_data = response.json()

if response_data and "choices" in response_data and len(response_data["choices"]) > 0:

assistant_response = response_data["choices"][0]["message"]["content"]

print("\nپاسخ مدل (غیر جریانی):")

print(assistant_response)

else:

print("پاسخی از مدل دریافت نشد یا فرمت آن نامعتبر است.")

print(json.dumps(response_data, indent=2, ensure_ascii=False))

except requests.exceptions.RequestException as err:

print(f"خطا: {err}")

if hasattr(err, 'response') and err.response is not None:

print(f"پاسخ سرور: {err.response.text}")

except json.JSONDecodeError:

print("خطا در تجزیه JSON پاسخ.")

print(f"پاسخ خام: {response.text if response else 'No response'}")

# مثال ۱: استفاده از GPT-4o با temperature پایین برای دقت بالا

messages_gpt4o = [

{"role": "system", "content": "شما یک دستیار هوش مصنوعی بسیار دقیق و حرفه‌ای در زمینه تاریخ ایران هستید."},

{"role": "user", "content": "مهمترین دلایل سقوط ساسانیان چه بود؟"}

]

get_completion("openai/gpt-4o", messages_gpt4o, temperature=0.2, max_tokens=300)

# مثال ۲: استفاده از Mixtral برای ایده‌پردازی با temperature بالا (جریانی)

messages_mixtral = [

{"role": "system", "content": "شما یک ایده‌پرداز خلاق برای کمپین‌های تبلیغاتی هستید."},

{"role": "user", "content": "چند ایده خلاقانه برای کمپین تبلیغاتی یک محصول نوشیدنی انرژی‌زا با طعم انار ارائه دهید."}

]

get_completion("mistralai/mixtral-8x7b-instruct", messages_mixtral, temperature=0.9, max_tokens=400, stream=True)

# مثال ۳: استفاده از GPT-3.5-turbo برای خلاصه‌سازی یک متن طولانی

long_text = """

هوش مصنوعی (AI) شاخه‌ای از علوم کامپیوتر است که به توسعه ماشین‌هایی می‌پردازد که می‌توانند همانند انسان فکر کرده، یاد بگیرند و عمل کنند. این حوزه شامل زیرشاخه‌های متعددی مانند یادگیری ماشین (Machine Learning)، پردازش زبان طبیعی (Natural Language Processing - NLP)، بینایی کامپیوتر (Computer Vision) و رباتیک است. هدف نهایی AI ایجاد سیستم‌هایی است که قادر به انجام وظایفی باشند که به طور معمول به هوش انسانی نیاز دارند. از کاربردهای روزمره AI می‌توان به دستیارهای صوتی، سیستم‌های توصیه‌گر، خودروهای خودران و تشخیص پزشکی اشاره کرد. با پیشرفت‌های اخیر در یادگیری عمیق (Deep Learning) و مدل‌های زبانی بزرگ (LLMs)، توانایی‌های هوش مصنوعی به طرز چشمگیری افزایش یافته و تأثیرات آن در صنایع مختلف، از جمله تولید محتوا (مانند تولید محتوای متنی)، بسیار مشهود است.

"""

messages_summarize = [

{"role": "system", "content": "شما یک خلاصه کننده حرفه‌ای هستید. متن زیر را به فارسی در حداکثر ۵۰ کلمه خلاصه کنید."},

{"role": "user", "content": long_text}

]

get_completion("openai/gpt-3.5-turbo", messages_summarize, temperature=0.1, max_tokens=100)

```

با اجرای این کد، می‌توانید تفاوت در خروجی مدل‌های مختلف و تأثیر پارامترهایی مانند temperature و stream را مشاهده کنید. این انعطاف‌پذیری به شما امکان می‌دهد تا OpenRouter API را برای طیف وسیعی از کاربردها، از جمله تولید پرامپت و یادگیری هوش مصنوعی، سفارشی‌سازی کنید.

تست Axeto

در این بخش، به بررسی عملی و تست OpenRouter API با تمرکز بر نیازهای کاربران Axeto می‌پردازیم. هدف ما ارزیابی عملکرد مدل‌های مختلف در پاسخگویی به پرامپت‌های فارسی و کاربردهای خاص Axeto است.

برای این تست، ما از چند مدل محبوب و پرکاربرد در OpenRouter استفاده می‌کنیم و پرامپت‌های فارسی را با سناریوهای مختلف (تولید محتوا، ایده‌پردازی، ترجمه) به آن‌ها ارسال می‌کنیم.

پرامپت‌های تست:

1. تولید محتوای متنی (بلاگ):

* سیستم: "شما یک نویسنده بلاگ متخصص در زمینه فناوری هستید که به زبان فارسی محتوای جذاب تولید می‌کنید."

* کاربر: "یک مقدمه کوتاه (حدود ۱۰۰ کلمه) برای مقاله‌ای با عنوان 'آینده هوش مصنوعی در تولید محتوا' بنویسید."

2. ایده‌پردازی (شبکه‌های اجتماعی):

* سیستم: "شما یک مدیر بازاریابی خلاق برای شبکه‌های اجتماعی هستید."

* کاربر: "۵ ایده برای پست اینستاگرام درباره مزایای استفاده از Axeto برای خالقان محتوا ارائه دهید."

3. ترجمه و خلاصه‌سازی:

* سیستم: "شما یک مترجم و خلاصه‌کننده حرفه‌ای هستید."

* کاربر: "متن انگلیسی زیر را به فارسی ترجمه کرده و در حداکثر ۳۰ کلمه خلاصه کنید: 'Artificial intelligence is rapidly transforming the creative industry, enabling artists and designers to generate novel ideas and automate repetitive tasks, thus fostering innovation and efficiency.'"

جدول نتایج تست:

| مدل OpenRouter | پرامپت ۱ (مقدمه بلاگ) OpenRouter API: دروازه‌ای به مدل‌های هوش مصنوعی پیشرفته

OpenRouter API یک پلتفرم قدرتمند است که دسترسی یکپارچه و کارآمدی را به طیف وسیعی از مدل‌های هوش مصنوعی (AI) پیشرفته، از جمله مدل‌های زبانی بزرگ (LLMs) و مدل‌های چندوجهی (Multimodal Models)، برای توسعه‌دهندگان و خالقان محتوا فراهم می‌کند. این آموزش جامع، شما را با تمام جنبه‌های OpenRouter API آشنا کرده و نحوه استفاده از آن را برای پروژه‌های خود، گام به گام توضیح می‌دهد.

تحلیل Axeto

Axeto (axeto.ai) به عنوان یک پلتفرم پیشرو در تولید محتوا با هوش مصنوعی، از مدل‌های هوش مصنوعی قدرتمند برای ارائه خدمات خود استفاده می‌کند. ادغام با OpenRouter API مزایای قابل توجهی برای کاربران Axeto به ارمغان می‌آورد:

• تنوع مدل‌ها: Axeto می‌تواند به راحتی به طیف وسیعی از مدل‌های موجود در OpenRouter دسترسی پیدا کند. این به معنای آن است که کاربران Axeto می‌توانند از جدیدترین و بهترین مدل‌ها برای تولید محتوای متنی، تصویری، و حتی ویدئویی بهره‌مند شوند. برای مثال، اگر یک مدل جدید با قابلیت‌های بی‌نظیر برای تولید تصویر منتشر شود، Axeto می‌تواند به سرعت آن را از طریق OpenRouter در اختیار کاربران خود قرار دهد.
• انعطاف‌پذیری در قیمت‌گذاری: OpenRouter با ارائه مدل‌های مختلف با قیمت‌های متفاوت، به Axeto این امکان را می‌دهد تا گزینه‌های قیمت‌گذاری متنوعی را به کاربران خود ارائه دهد. کاربران می‌توانند بر اساس نیاز و بودجه خود، بین مدل‌های با کیفیت بالا و گران‌تر یا مدل‌های مقرون به صرفه‌تر انتخاب کنند.
• پشتیبانی از زبان فارسی: بسیاری از مدل‌های موجود در OpenRouter، از جمله مدل‌های پیشرفته GPT و Claude، عملکرد بسیار خوبی در زبان فارسی دارند. این امر برای کاربران ایرانی Axeto که به دنبال تولید محتوای با کیفیت فارسی هستند، حیاتی است. Axeto می‌تواند از این قابلیت برای ارائه خدمات بهتر در تولید محتوای متنی فارسی، تولید پرامپت‌های فارسی و حتی ترجمه استفاده کند.
• کاهش پیچیدگی فنی: به جای اینکه Axeto مجبور باشد برای هر مدل به صورت جداگانه API آن را مدیریت کند، OpenRouter یک رابط یکپارچه فراهم می‌کند. این موضوع باعث می‌شود که Axeto بتواند زمان و منابع خود را بر روی بهبود تجربه کاربری و ارائه ویژگی‌های جدید متمرکز کند، نه بر روی مدیریت زیرساخت‌های پیچیده API.
• آزمایش و بهینه‌سازی آسان: Axeto می‌تواند به راحتی مدل‌های مختلف را از طریق OpenRouter آزمایش کند تا بهترین مدل را برای هر نوع کاربرد خاص (مثلاً تولید عنوان، نوشتن بدنه مقاله، یا خلاصه‌سازی) پیدا کند. این به Axeto کمک می‌کند تا همواره بهترین عملکرد را به کاربران خود ارائه دهد.

نظر عملی برای کاربران Axeto:

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

• پرامپت‌های خود را بهینه کنید: با توجه به اینکه مدل‌های مختلف ممکن است به پرامپت‌های متفاوتی پاسخ بهتری دهند، می‌توانید با یادگیری هوش مصنوعی و آزمایش پرامپت‌های مختلف، بهترین نتیجه را از Axeto بگیرید.
• از تنوع مدل‌ها بهره‌مند شوید: حتی اگر مستقیماً مدل‌ها را انتخاب نکنید، Axeto ممکن است در پشت صحنه از مدل‌های مختلفی برای وظایف گوناگون استفاده کند. این به معنای آن است که شما همیشه بهترین ابزار را برای کار خود در اختیار دارید.
• بهترین کیفیت را انتظار داشته باشید: Axeto با دسترسی به مدل‌های پیشرفته OpenRouter، می‌تواند محتوایی با کیفیت بالا، خلاقانه و مرتبط با نیازهای شما تولید کند. این امر به ویژه برای تولید پرامپت‌های پیچیده و خلاقانه بسیار مفید است.

در نهایت، ادغام Axeto با OpenRouter API نشان‌دهنده تعهد Axeto به ارائه پیشرفته‌ترین ابزارها و بهترین تجربه به جامعه خالقان محتوا است.

کد نمونه

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

import os
import requests
import json
from dotenv import load_dotenv

# --- ۱. بارگذاری متغیرهای محیطی ---
# اطمینان حاصل کنید که یک فایل .env در کنار این فایل پایتون دارید
# و کلید API خود را به شکل زیر در آن ذخیره کرده‌اید:
# OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
load_dotenv()

OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")
OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions"

if not OPENROUTER_API_KEY:
    raise ValueError("کلید OPENROUTER_API_KEY در متغیرهای محیطی یا فایل .env یافت نشد. لطفا آن را تنظیم کنید.")

# --- ۲. تابع کمکی برای ارسال درخواست به OpenRouter ---
def call_openrouter_api(model_name, messages, temperature=0.7, max_tokens=500, stream=False, **kwargs):
    """
    این تابع یک درخواست تکمیل چت به OpenRouter API ارسال می‌کند.

    Args:
        model_name (str): نام مدلی که می‌خواهید استفاده کنید (مثلاً "openai/gpt-3.5-turbo").
        messages (list): لیستی از دیکشنری‌های پیام‌ها با نقش ('role') و محتوا ('content').
        temperature (float): کنترل خلاقیت مدل (۰.۰ برای پاسخ‌های قطعی، ۱.۰ برای خلاقیت بیشتر).
        max_tokens (int): حداکثر تعداد توکن‌های تولید شده در پاسخ.
        stream (bool): اگر True باشد، پاسخ به صورت جریانی دریافت می‌شود.
        **kwargs: پارامترهای اضافی برای API (مانند top_p, frequency_penalty, seed).

    Returns:
        dict or None: پاسخ کامل JSON از API در حالت غیر جریانی، یا None در حالت جریانی.
    """
    payload = {
        "model": model_name,
        "messages": messages,
        "temperature": temperature,
        "max_tokens": max_tokens,
        "stream": stream,
        **kwargs # اضافه کردن پارامترهای اضافی
    }

    headers = {
        "Authorization": f"Bearer {OPENROUTER_API_KEY}",
        "Content-Type": "application/json",
        "HTTP-Referer": "https://axeto.ai", # برای ردیابی استفاده در Axeto
        "X-Title": "Axeto OpenRouter Tutorial", # عنوان پروژه برای ردیابی
    }

    print(f"\n--- در حال ارسال درخواست به مدل: {model_name} ---")
    print(f"پارامترها: temperature={temperature}, max_tokens={max_tokens}, stream={stream}")

    try:
        response = requests.post(OPENROUTER_API_URL, headers=headers, data=json.dumps(payload), stream=stream)
        response.raise_for_status() # بررسی خطاهای HTTP

        if stream:
            print("پاسخ جریانی:")
            full_response_content = ""
            for chunk in response.iter_lines():
                if chunk:
                    try:
                        decoded_chunk = chunk.decode('utf-8')
                        if decoded_chunk.startswith("data: "):
                            json_data = decoded_chunk[len("data: "):]
                            if json_data == "[DONE]":
                                break
                            chunk_data = json.loads(json_data)
                            if "choices" in chunk_data and len(chunk_data["choices"]) > 0:
                                delta = chunk_data["choices"][0]["delta"]
                                if "content" in delta:
                                    content_part = delta["content"]
                                    print(content_part, end="", flush=True)
                                    full_response_content += content_part
                        # else: # برای دیباگ کردن فرمت‌های غیرمنتظره
                        #     print(f"Non-data chunk: {decoded_chunk}")
                    except json.JSONDecodeError:
                        # print(f"خطا در تجزیه JSON بخش جریانی: {decoded_chunk}")
                        pass
            print("\n") # یک خط جدید پس از اتمام پاسخ جریانی
            return {"full_content": full_response_content} # می‌توانیم محتوای کامل را برگردانیم
        else:
            response_data = response.json()
            if response_data and "choices" in response_data and len(response_data["choices"]) > 0:
                assistant_response = response_data["choices"][0]["message"]["content"]
                print("\nپاسخ مدل (غیر جریانی):")
                print(assistant_response)
                return response_data
            else:
                print("پاسخی از مدل دریافت نشد یا فرمت آن نامعتبر است.")
                print(json.dumps(response_data, indent=2, ensure_ascii=False))
                return None

    except requests.exceptions.HTTPError as errh:
        print(f"خطای HTTP: {errh}")
        print(f"پاسخ سرور: {errh.response.text}")
        return None
    except requests.exceptions.ConnectionError as errc:
        print(f"خطای اتصال: {errc}")
        return None
    except requests.exceptions.Timeout as errt:
        print(f"خطای زمان‌بندی: {errt}")
        return None
    except requests.exceptions.RequestException as err:
        print(f"خطای کلی: {err}")
        return None
    except json.JSONDecodeError:
        print("خطا در تجزیه JSON پاسخ.")
        print(f"پاسخ خام: {response.text if 'response' in locals() else 'No response'}")
        return None

# --- ۳. مثال‌های کاربردی ---

# مثال ۱: تولید محتوای متنی برای یک پست بلاگ با GPT-3.5-turbo (غیر جریانی)
messages_blog = [
    {"role": "system", "content": "شما یک نویسنده بلاگ متخصص در زمینه توسعه وب هستید که به زبان فارسی محتوای جذاب تولید می‌کنید."},
    {"role": "user", "content": "یک پاراگراف مقدمه برای مقاله‌ای با عنوان '۱۰ نکته برای بهبود سئو وب‌سایت در سال ۲۰۲۴' بنویسید."}
]
call_openrouter_api(
    model_name="openai/gpt-3.5-turbo",
    messages=messages_blog,
    temperature=0.6,
    max_tokens=200
)

# مثال ۲: ایده‌پردازی برای نام یک محصول جدید با Mixtral (جریانی)
messages_product_name = [
    {"role": "system", "content": "شما یک متخصص برندینگ و ایده‌پردازی هستید."},
    {"role": "user", "content": "چندین نام خلاقانه و جذاب برای یک اپلیکیشن موبایل ایرانی ارائه دهید که به کاربران در مدیریت کارهای روزمره و برنامه‌ریزی کمک می‌کند. نام‌ها باید فارسی یا دارای ریشه فارسی باشند."}
]
call_openrouter_api(
    model_name="mistralai/mixtral-8x7b-instruct",
    messages=messages_product_name,
    temperature=0.8,
    max_tokens=300,
    stream=True
)

# مثال ۳: تولید یک پرامپت برای تولید تصویر با GPT-4o (چند وجهی)
# توجه: GPT-4o یک مدل چند وجهی است، اما OpenRouter API برای chat completions
# عمدتاً خروجی متنی می‌دهد. برای تولید تصویر واقعی، باید از APIهای مخصوص آن
# مانند DALL-E یا Stable Diffusion استفاده کنید و پرامپت را از اینجا بگیرید.
# برای اطلاعات بیشتر، به [تولید تصویر با Axeto](/generate/image) مراجعه کنید.
messages_image_prompt = [
    {"role": "system", "content": "شما یک متخصص پرامپت‌نویسی برای تولید تصاویر هنری با هوش مصنوعی هستید."},
    {"role": "user", "content": "یک پرامپت دقیق و خلاقانه برای تولید تصویری از یک 'شهر باستانی فارسی در آینده‌ای دور، با معماری تلفیقی از سنت و فناوری پیشرفته، و آسمانی پر از وسایل نقلیه پرنده' ارائه دهید."}
]
call_openrouter_api(
    model_name="openai/gpt-4o",
    messages=messages_image_prompt,
    temperature=0.9,
    max_tokens=150,
    top_p=0.9
)

# مثال ۴: خلاصه‌سازی یک خبر با Claude-3-Haiku (غیر جریانی)
news_article = """
اخیراً، یک شرکت فناوری ایرانی موفق به توسعه پلتفرمی مبتنی بر هوش مصنوعی شده است که قادر به تحلیل داده‌های پزشکی با دقت بالا و ارائه پیشنهاداتی برای تشخیص زودهنگام بیماری‌ها است. این پلتفرم با استفاده از الگوریتم‌های یادگیری عمیق، حجم عظیمی از اطلاعات بیماران را پردازش کرده و الگوهایی را شناسایی می‌کند که ممکن است از چشم پزشکان پنهان بماند. کارشناسان معتقدند این دستاورد می‌تواند انقلابی در حوزه سلامت دیجیتال ایران ایجاد کند و به بهبود کیفیت مراقبت‌های بهداشتی کمک شایانی نماید. این پلتفرم در حال حاضر در مرحله آزمایش بالینی قرار دارد و نتایج اولیه بسیار امیدوارکننده بوده‌اند.
"""
messages_summarize_news = [
    {"role": "system", "content": "شما یک دستیار هوش مصنوعی هستید که خبرها را به فارسی در حداکثر ۴۰ کلمه خلاصه می‌کنید."},
    {"role": "user", "content": f"خبر زیر را خلاصه کنید: {news_article}"}
]
call_openrouter_api(
    model_name="anthropic/claude-3-haiku", # یک مدل سریع و مقرون به صرفه از Claude
    messages=messages_summarize_news,
    temperature=0.3,
    max_tokens=70
)

print("\n--- پایان اجرای نمونه کدها ---")

نحوه اجرای کد:

1. ذخیره: کد بالا را در یک فایل پایتون (مثلاً openrouter_demo.py) ذخیره کنید.

2. فایل .env: یک فایل به نام .env در همان دایرکتوری ایجاد کنید و کلید API خود را به شکل OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY" در آن قرار دهید.

3. نصب کتابخانه‌ها: اگر قبلاً این کار را نکرده‌اید، requests و python-dotenv را نصب کنید: pip install requests python-dotenv

4. اجرا: فایل را از طریق ترمینال اجرا کنید: python openrouter_demo.py

با اجرای این کد، شما می‌توانید تعامل با مدل‌های مختلف OpenRouter را تجربه کنید و خروجی‌های متفاوتی را بر اساس پارامترهای ارسالی مشاهده نمایید. این کد یک نقطه شروع عالی برای ادغام OpenRouter API در پروژه‌های شماست.

خطاهای رایج

هنگام کار با هر API، ممکن است با خطاهایی مواجه شوید. درک این خطاها و نحوه رفع آن‌ها برای توسعه‌ای روان ضروری است. در اینجا برخی از خطاهای رایج در OpenRouter API و راه‌حل‌های آن‌ها آورده شده است:

1. 401 Unauthorized (خطای احراز هویت):

* توضیح: این خطا به این معنی است که کلید API شما نامعتبر است یا در هدر Authorization به درستی ارسال نشده است.

* راه‌حل:

* مطمئن شوید که OPENROUTER_API_KEY را به درستی کپی کرده‌اید و هیچ فضای اضافی در ابتدا یا انتهای آن وجود ندارد.

* بررسی کنید که کلید API منقضی نشده باشد (اگر OpenRouter چنین قابلیتی را ارائه دهد).

* مطمئن شوید که هدر Authorization به شکل Bearer YOUR_API_KEY تنظیم شده باشد.

* اگر از متغیرهای محیطی استفاده می‌کنید، بررسی کنید که متغیر به درستی بارگذاری شده باشد.

2. 400 Bad Request (خطای درخواست نامعتبر):

* توضیح: این خطا نشان می‌دهد که درخواست شما از نظر ساختاری مشکل دارد یا پارامترهای نامعتبری ارسال کرده‌اید.

* راه‌حل:

* JSON نامعتبر: مطمئن شوید که payload شما یک JSON معتبر است. از json.dumps() برای تبدیل دیکشنری پایتون به رشته JSON استفاده کنید.

* پارامترهای اشتباه: نام مدل (model), ساختار messages (شامل role و content), temperature, max_tokens و سایر پارامترها را بررسی کنید. به مستندات OpenRouter برای پارامترهای صحیح مراجعه کنید.

* مدل نامعتبر: مطمئن شوید که نام مدلی که انتخاب کرده‌اید، (openai/gpt-3.5-turbo یا mistralai/mixtral-8x7b-instruct) دقیقاً صحیح و در OpenRouter موجود است.

* محدودیت‌های پارامتر: مقادیر temperature باید بین ۰.۰ و ۱.۰ باشد، max_tokens باید یک عدد صحیح مثبت باشد.

3. 404 Not Found (منبع یافت نشد):

* توضیح: این خطا معمولاً به دلیل URL Endpoint اشتباه رخ می‌دهد.

* راه‌حل: مطمئن شوید که OPENROUTER_API_URL شما دقیقاً https://openrouter.ai/api/v1/chat/completions است.

4. 429 Too Many Requests (درخواست‌های زیاد):

* توضیح: شما در یک بازه زمانی مشخص، تعداد زیادی درخواست ارسال کرده‌اید و به محدودیت نرخ (Rate Limit) رسیده‌اید.

* راه‌حل:

* درخواست‌های خود را با تأخیر (مثلاً با استفاده از time.sleep() در پایتون) ارسال کنید.

* از الگوی "Exponential Backoff" استفاده کنید: در صورت دریافت این خطا، کمی صبر کنید و دوباره امتحان کنید؛ اگر باز هم خطا گرفتید، زمان انتظار را بیشتر کنید.

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

5. 500 Internal Server Error (خطای داخلی سرور):

* توضیح: این خطا از سمت سرور OpenRouter یا مدل هوش مصنوعی رخ داده است.

* راه‌حل:

* این خطا معمولاً از سمت شما نیست. می‌توانید درخواست را پس از کمی تأخیر دوباره امتحان کنید.

* اگر مشکل ادامه داشت، وضعیت OpenRouter را در صفحه وضعیت OpenRouter بررسی کنید.

* با پشتیبانی OpenRouter تماس بگیرید.

6. 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout:

* توضیح: این خطاها معمولاً نشان‌دهنده مشکلات موقتی در دسترس بودن سرویس یا شبکه هستند.

* راه‌حل: کمی صبر کنید و درخواست را دوباره امتحان کنید.

7. خطا در تجزیه JSON (json.JSONDecodeError):

* توضیح: پاسخ دریافتی از سرور یک JSON معتبر نیست.

* راه‌حل: این می‌تواند به دلیل خطای سرور یا قطع شدن اتصال باشد. پاسخ خام (response.text) را پرینت کنید تا ببینید چه چیزی دریافت کرده‌اید.

نکات کلی برای رفع اشکال:

• لاگ‌برداری: همیشه درخواست‌ها و پاسخ‌های کامل (به خصوص در زمان خطا) را لاگ کنید. این اطلاعات برای تشخیص مشکل بسیار ارزشمند هستند.
• مستندات: همیشه به مستندات رسمی OpenRouter مراجعه کنید تا از آخرین تغییرات API و پارامترهای صحیح مطلع شوید.
• جامعه: از جوامع آنلاین مانند Stack Overflow یا انجمن‌های OpenRouter برای یافتن راه‌حل‌ها استفاده کنید.
• تست‌های کوچک: اگر با یک مشکل پیچیده روبرو شدید، سعی کنید مشکل را به کوچک‌ترین قسمت ممکن تقسیم کنید و هر بخش را جداگانه تست کنید.

با درک این خطاهای رایج و راه‌حل‌های آن‌ها، می‌توانید فرآیند توسعه خود را با OpenRouter API بسیار کارآمدتر کنید و به سرعت مشکلات را برطرف نمایید.

جمع‌بندی

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

نکات کلیدی که آموختیم:

• OpenRouter API یک دروازه واحد برای دسترسی به بیش از ۱۰۰ مدل هوش مصنوعی مختلف است که پیچیدگی ادغام را کاهش می‌دهد.
• کلید API شما برای احراز هویت ضروری است و باید به صورت امن نگهداری شود.
• ساختار درخواست‌ها شبیه به OpenAI API است و شامل model, messages, و پارامترهای اختیاری مانند temperature و max_tokens می‌شود.
• تنوع مدل‌ها به شما امکان می‌دهد بهترین مدل را برای نیازهای خاص پروژه خود از نظر کیفیت، سرعت و هزینه انتخاب کنید.
• پارامترهای پیشرفته کنترل دقیقی بر روی رفتار مدل، از جمله خلاقیت و طول پاسخ، فراهم می‌کنند.
• Axeto می‌تواند با بهره‌گیری از OpenRouter، به کاربران خود دسترسی به مدل‌های متنوع و پیشرفته را برای تولید محتوا ارائه دهد و تجربه کاربری را بهبود بخشد.
• مدیریت خطاها برای توسعه پایدار و رفع اشکال سریع اهمیت دارد.

با تسلط بر OpenRouter API، شما اکنون ابزاری قدرتمند در اختیار دارید تا قابلیت‌های هوش مصنوعی را در برنامه‌ها، خدمات و پروژه‌های خلاقانه خود ادغام کنید. چه در حال توسعه یک دستیار هوش مصنوعی باشید، چه بخواهید محتوای متنی یا تصویری تولید کنید، یا حتی یک سیستم پیچیده برای تولید پرامپت بسازید، OpenRouter ابزارهای لازم را در اختیار شما قرار می‌دهد.

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

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

منبع

• مستندات رسمی OpenRouter API
• لیست مدل‌های OpenRouter
• صفحه قیمت‌گذاری OpenRouter
• صفحه وضعیت OpenRouter
• Axeto AI - تولید محتوا با هوش مصنوعی
• Axeto AI - تولید تصویر
• Axeto AI - تولید متن
• Axeto AI - پرامپت‌ها
• Axeto AI - مدل‌ها
• Axeto AI - قیمت‌گذاری
• Axeto AI - یادگیری هوش مصنوعی
• Axeto AI - تاپیک OpenRouter
• OpenAI API Documentation (برای مقایسه ساختار درخواست‌ها)
• Requests: HTTP for Humans (کتابخانه پایتون)
• python-dotenv (برای مدیریت متغیرهای محیطی)
• JSON (JavaScript Object Notation)
• What is an API?
• Understanding Large Language Models (LLMs)
• Multimodal AI Explained
• Rate Limiting Explained
• HTTP Status Codes