اتصال OpenAI Python SDK به پیکو هوش

کتابخانه‌ی رسمی openai برای پایتون رایج‌ترین راه برای صدا زدن مدل‌های زبانی است. چون API پیکو هوش با قالب درخواست و پاسخ OpenAI سازگار است، برای اتصال لازم نیست هیچ بخشی از منطق برنامه را بازنویسی کنید؛ فقط آدرس پایه و کلید تغییر می‌کند.

مزیت عملی این روش این است که همان کد می‌تواند به مدل‌های OpenAI، Anthropic، Google، DeepSeek و دیگر مدل‌های کاتالوگ وصل شود. برای هر درخواست فقط مقدار پارامتر model را عوض می‌کنید و هزینه از کیف پول تومانی شما کم می‌شود.

پیش‌نیازها

• یک حساب پیکو هوش و یک کلید API از داشبورد (کلید فقط یک‌بار کامل نمایش داده می‌شود).
• شناسه‌ی دقیق مدل از کاتالوگ؛ در مثال‌ها از gpt-6-sol و claude-sonnet-5-5 استفاده شده است.
• کمی موجودی در کیف پول تومانی یا اعتبار؛ تعرفه را در صفحه‌ی قیمت‌ها ببینید.

راه‌اندازی گام‌به‌گام

1. ۱نصب کتابخانه

   پایتون ۳.۸ یا بالاتر لازم است. کتابخانه را در محیط مجازی پروژه نصب کنید.

   کپی

   pip install --upgrade openai

2. ۲ساخت کلاینت با آدرس پایه‌ی پیکو هوش

   پارامترهای base_url و api_key را هنگام ساخت کلاینت بدهید. کلید را از داشبورد بگیرید و هرگز داخل مخزن کد ذخیره نکنید.

   کپی

   import os
   from openai import OpenAI
   
   client = OpenAI(
       base_url="https://api.picoai.ir/v1",
       api_key=os.environ.get("PICOAI_API_KEY", "YOUR_API_KEY"),
   )
   
   reply = client.chat.completions.create(
       model="gpt-6-sol",
       messages=[{"role": "user", "content": "یک جمله درباره‌ی تهران بنویس."}],
   )
   print(reply.choices[0].message.content)

3. ۳استریم پاسخ

   برای نمایش تدریجی متن، stream=True بدهید و تکه‌ها را بخوانید. پیکو هوش استریم SSE را با همان قالب OpenAI برمی‌گرداند.

   کپی

   stream = client.chat.completions.create(
       model="claude-sonnet-5-5",
       messages=[{"role": "user", "content": "سه نکته برای نوشتن پرامپت خوب بگو."}],
       stream=True,
   )
   for chunk in stream:
       delta = chunk.choices[0].delta.content
       if delta:
           print(delta, end="", flush=True)

4. ۴تنظیم از طریق متغیر محیطی (اختیاری)

   اگر نمی‌خواهید آدرس را در کد بنویسید، کتابخانه متغیرهای OPENAI_BASE_URL و OPENAI_API_KEY را هم می‌خواند و کلاینت را بدون آرگومان می‌سازید.

   کپی

   export OPENAI_BASE_URL="https://api.picoai.ir/v1"
   export OPENAI_API_KEY="YOUR_API_KEY"
   python -c "from openai import OpenAI; print(OpenAI().models.list().data[0].id)"

تست سریع اتصال

پیش از نوشتن منطق برنامه، یک بار فهرست مدل‌ها را بگیرید. اگر پاسخ ۲۰۰ و فهرستی از شناسه‌ها برگشت، کلید، شبکه و آدرس درست است و هر مشکل بعدی مربوط به تنظیمات OpenAI Python SDK خواهد بود.

curl https://api.picoai.ir/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

نکته‌های کاربردی برای OpenAI Python SDK

• برای کارهای سبک و پرحجم (دسته‌بندی، استخراج) از مدل‌های اقتصادی کاتالوگ استفاده کنید و مدل‌های پرچمدار را برای استدلال سنگین نگه دارید.
• timeout و تعداد تلاش مجدد را در کلاینت تنظیم کنید: OpenAI(max_retries=2, timeout=60). مسیریابی چندمسیره‌ی پیکو هوش خطاهای زیرساختی را در سمت ما پنهان می‌کند، اما محدودیت شبکه‌ی خود شما همچنان لازم است.
• در سرویس‌های وب از AsyncOpenAI استفاده کنید تا درخواست‌های هم‌زمان رشته‌ی اصلی را مسدود نکنند.

عیب‌یابی

هزینه و صورتحساب

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