آموزش ساخت چت‌بات هوش مصنوعی با پایتون و API

آموزش ساخت چت‌بات هوش مصنوعی با پایتون و API؛ قدم‌به‌قدم از صفر

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

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

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

برای اتصال از Sinox API استفاده می‌کنیم؛ اما ساختار کد بر پایه OpenAI SDK است و می‌توان آن را برای سایر ارائه‌دهندگان سازگار نیز تنظیم کرد.

چت‌بات هوش مصنوعی چیست و چگونه کار می‌کند؟

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

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

فرایند کلی به این صورت است:

1. کاربر پیامی در برنامه وارد می‌کند.

2. برنامه پیام و تاریخچه مرتبط را به API می‌فرستد.

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

4. پاسخ مدل به برنامه برمی‌گردد.

5. برنامه پاسخ را نمایش می‌دهد و گفتگو را ادامه می‌دهد.

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

پیش‌نیازهای ساخت چت‌بات با Python

برای انجام این پروژه به ابزارهای پیچیده نیاز نداریم.

ابتدا با دستور زیر نسخه پایتون را بررسی کنید:

python --version

در بعضی سیستم‌ها، به‌ویژه macOS، ممکن است لازم باشد به‌جای python از python3 استفاده کنید.

نصب کتابخانه OpenAI

برای نصب کتابخانه رسمی OpenAI در پایتون، دستور زیر را اجرا کنید:

python -m pip install --upgrade openai

این کتابخانه علاوه بر API رسمی OpenAI، برای ارتباط با سرویس‌های دارای Endpoint سازگار نیز قابل استفاده است.

اگر با مفهوم OpenAI-Compatible آشنایی ندارید، پیشنهاد می‌کنیم ابتدا مقاله «API سازگار با OpenAI چیست؟» را مطالعه کنید.

دریافت API Key و انتخاب مدل هوش مصنوعی

برای ارسال درخواست به مدل، باید یک API Key معتبر داشته باشید.

در این آموزش از Sinox API استفاده می‌کنیم که دسترسی به مدل‌های مختلف هوش مصنوعی را از طریق یک رابط مشترک فراهم می‌کند.

مراحل کلی دریافت کلید:

1. وارد داشبورد Sinox شوید.

2. از بخش کلیدهای API، یک کلید جدید بسازید.

3. نوع پکیج توکنی یا ریکوستی را انتخاب کنید.

4. کلید را کپی کرده و در محلی امن نگه دارید.

5. شناسه مدل مناسب را از فهرست مدل‌ها بردارید.

نکته مهم: در Sinox، شناسه مدل باید با نوع کلید مطابقت داشته باشد. برای مثال، شناسه مدل در پکیج توکنی می‌تواند با پیشوند t- شروع شود، درحالی‌که شناسه همان مدل برای کلید ریکوستی این پیشوند را ندارد.

ذخیره امن کلید API

بهتر است کلید API را مستقیماً داخل فایل پایتون قرار ندهید.

در PowerShell ویندوز می‌توانید از دستور زیر استفاده کنید:

$env:SINOX_API_KEY="YOUR_API_KEY"

در macOS یا Linux:

export SINOX_API_KEY="YOUR_API_KEY"

این متغیر برای نشست فعلی ترمینال تنظیم می‌شود. بنابراین باید برنامه را در همان محیط اجرا کنید.

ساخت اولین نسخه چت‌بات هوش مصنوعی

حالا یک پوشه برای پروژه بسازید و داخل آن فایلی با نام chatbot.py ایجاد کنید.

کد زیر را در فایل قرار دهید:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SINOX_API_KEY"],
    base_url="https://sinoxapi.com/v1"
)

MODEL = "YOUR_MODEL_ID"

messages = [
    {
        "role": "system",
        "content": "تو یک دستیار فارسی‌زبان، دقیق و مفید هستی."
    }
]

print("چت‌بات آماده است! برای خروج، exit بنویسید.")

while True:
    user_input = input("\nشما: ").strip()

    if user_input.lower() in ("exit", "quit"):
        print("خدانگهدار!")
        break

    if not user_input:
        continue

    messages.append({
        "role": "user",
        "content": user_input
    })

    try:
        response = client.chat.completions.create(
            model=MODEL,
            messages=messages,
            max_tokens=1000
        )

        answer = response.choices[0].message.content or ""

        print(f"\nربات: {answer}")

        messages.append({
            "role": "assistant",
            "content": answer
        })

    except Exception as error:
        messages.pop()
        print(f"\nخطا در دریافت پاسخ: {error}")

قبل از اجرای برنامه، مقدار YOUR_MODEL_ID را با شناسه معتبر مدل از داشبورد Sinox جایگزین کنید.

برای نمونه، اگر از کلید توکنی و مدل t-claude-sonnet-5 استفاده می‌کنید، باید مطمئن شوید این شناسه در حساب شما فعال است.

اجرای چت‌بات در ترمینال

در پوشه پروژه، دستور زیر را اجرا کنید:

python chatbot.py

در macOS ممکن است دستور مناسب python3 chatbot.py باشد.

اگر تنظیمات درست باشند، برنامه پیام شروع را نمایش می‌دهد و منتظر سؤال شما می‌ماند.

نمونه‌ای از گفتگو:

چت‌بات آماده است! برای خروج، exit بنویسید.

شما: سلام! پایتون چیست؟

ربات: پایتون یک زبان برنامه‌نویسی محبوب و
چندمنظوره است که برای توسعه وب، تحلیل داده
و هوش مصنوعی استفاده می‌شود.

شما: سه کاربرد مهمش را نام ببر.

ربات: توسعه وب، تحلیل داده و ساخت
برنامه‌های هوش مصنوعی.

این گفتگو یک خروجی نمونه است و متن پاسخ واقعی ممکن است متفاوت باشد.

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

برای درک بهتر برنامه، مهم‌ترین بخش‌های آن را بررسی می‌کنیم.

اتصال به API

در ابتدای برنامه، شیء OpenAI را ایجاد می‌کنیم:

client = OpenAI(
    api_key=os.environ["SINOX_API_KEY"],
    base_url="https://sinoxapi.com/v1"
)

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

برای استفاده از Sinox با OpenAI SDK، آدرس پایه باید با /v1 تمام شود.

نقش System Prompt

در بخش messages یک پیام با نقش system تعریف کرده‌ایم.

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

System Prompt به هدایت رفتار مدل کمک می‌کند، اما تضمین نمی‌کند که مدل همیشه تمام دستورها را دقیقاً رعایت کند.

حلقه گفتگو

دستور while True باعث می‌شود برنامه پس از هر پاسخ، منتظر پیام بعدی کاربر بماند.

وقتی کاربر exit یا quit وارد کند، حلقه متوقف می‌شود.

ارسال درخواست و دریافت پاسخ

متد client.chat.completions.create پیام‌ها را به API ارسال می‌کند.

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

response.choices[0].message.content

سپس پاسخ در ترمینال نمایش داده می‌شود.

چگونه حافظه مکالمه را به چت‌بات اضافه کنیم؟

یکی از تفاوت‌های مهم یک چت‌بات واقعی با برنامه ارسال یک درخواست ساده، مدیریت تاریخچه گفتگو است.

در APIهای مبتنی بر Chat Completions، مدل معمولاً تاریخچه مکالمه را به‌صورت خودکار بین درخواست‌های مستقل نگه نمی‌دارد. برنامه باید پیام‌های قبلی را دوباره ارسال کند.

در کد ما، متغیر messages این وظیفه را بر عهده دارد.

بعد از هر پیام کاربر، متن آن به فهرست اضافه می‌شود:

messages.append({
    "role": "user",
    "content": user_input
})

پس از دریافت پاسخ نیز پیام دستیار ذخیره می‌شود:

messages.append({
    "role": "assistant",
    "content": answer
})

به همین دلیل، وقتی در پیام دوم می‌گویید «سه کاربردش را نام ببر»، مدل می‌تواند از پیام قبلی متوجه شود درباره پایتون صحبت می‌کنید.

البته این حافظه فقط در زمان اجرای برنامه وجود دارد و با بسته شدن آن از بین می‌رود.

محدود کردن تاریخچه برای کاهش مصرف توکن

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

برای یک چت‌بات ساده، می‌توان فقط چند پیام اخیر را نگه داشت.

مثلاً پیش از ارسال درخواست، این کد را اضافه کنید:

recent_messages = [messages[0]] + messages[1:][-10:]

سپس در درخواست API به‌جای messages از recent_messages استفاده کنید.

در این حالت، System Prompt و حداکثر ۱۰ پیام اخیر ارسال می‌شوند.

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

چگونه مدل چت‌بات را تغییر دهیم؟

یکی از مزیت‌های استفاده از API سازگار با OpenAI، امکان تغییر مدل با اصلاح تنظیمات برنامه است.

برای مثال، می‌توانید شناسه مدل را در یک متغیر قرار دهید:

MODEL = "YOUR_MODEL_ID"

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

البته مدل‌های مختلف ممکن است از نظر سرعت، هزینه، کیفیت پاسخ، ظرفیت Context و قابلیت‌های فنی تفاوت داشته باشند.

بنابراین بهتر است پیش از انتخاب نهایی، عملکرد چند مدل را با سؤال‌های واقعی پروژه آزمایش کنید.

چگونه مصرف توکن و هزینه چت‌بات را کنترل کنیم؟

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

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

در صورت ارائه اطلاعات مصرف توسط Endpoint، می‌توانید آن را از پاسخ دریافت کنید:

if response.usage:
    print("توکن ورودی:", response.usage.prompt_tokens)
    print("توکن خروجی:", response.usage.completion_tokens)
    print("مجموع:", response.usage.total_tokens)

این بخش را پس از دریافت response در کد اصلی قرار دهید.

برای مدیریت بهتر هزینه، تاریخچه گفتگو را کنترل کنید، خروجی‌های غیرضروری را کاهش دهید و مدل مناسب هر وظیفه را انتخاب کنید.

برای یادگیری فرمول محاسبه هزینه، مقاله «توکن هوش مصنوعی چیست؟ آموزش محاسبه هزینه API» را مطالعه کنید.

خطاهای رایج هنگام ساخت چت‌بات با API

خطای 401: کلید API نامعتبر

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

مطمئن شوید مقدار SINOX_API_KEY در همان ترمینالی که برنامه را اجرا می‌کنید تنظیم شده است.

خطای 404: آدرس یا مدل اشتباه

بررسی کنید که Base URL در OpenAI SDK به شکل زیر باشد:

https://sinoxapi.com/v1

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

خطای 402: مشکل پکیج یا شناسه مدل

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

برای مثال، استفاده از شناسه توکنی با کلید ریکوستی ممکن است خطای billing_type_mismatch ایجاد کند.

خطای 429: محدودیت تعداد درخواست

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

در این شرایط، باید نرخ ارسال درخواست‌ها را کاهش دهید یا پس از مدتی دوباره تلاش کنید.

خطای قطع ارتباط یا Timeout

اگر اتصال شبکه ناپایدار باشد یا پردازش درخواست طول بکشد، ممکن است خطای Timeout رخ دهد.

برای بررسی مشکل، ابتدا با یک سؤال کوتاه و بدون تاریخچه طولانی اتصال را آزمایش کنید.

چگونه چت‌بات را به یک پروژه واقعی تبدیل کنیم؟

چت‌بات ترمینالی که ساختیم، نقطه شروع مناسبی برای پروژه‌های بزرگ‌تر است.

برای مثال، می‌توانید در مراحل بعد:

• با استفاده از FastAPI یک Backend برای چت‌بات بسازید.

• با HTML و JavaScript یک رابط گفتگوی تحت وب طراحی کنید.

• تاریخچه مکالمات را در پایگاه داده ذخیره کنید.

• چت‌بات را به تلگرام یا سامانه پشتیبانی متصل کنید.

• با روش RAG، پاسخ‌گویی بر اساس اسناد اختصاصی را اضافه کنید.

برای استفاده عمومی، باید احراز هویت کاربران، محدودیت درخواست، مدیریت خطا، محافظت از API Key و کنترل هزینه را نیز در نظر بگیرید.

نکته امنیتی: کلید API را هرگز داخل JavaScript سمت مرورگر قرار ندهید. درخواست‌های دارای کلید محرمانه باید از طریق Backend امن ارسال شوند.

سؤالات متداول درباره ساخت چت‌بات با پایتون

آیا برای ساخت چت‌بات هوش مصنوعی باید مدل را آموزش دهیم؟

خیر. با استفاده از API مدل‌های آماده می‌توانید بدون آموزش مدل از ابتدا، یک چت‌بات بسازید.

آیا می‌توان با Python یک چت‌بات فارسی ساخت؟

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

آیا ساخت چت‌بات با API رایگان است؟

نصب Python و کتابخانه OpenAI رایگان است، اما استفاده از API ممکن است بر اساس پکیج، تعداد درخواست یا مصرف توکن هزینه داشته باشد.

آیا چت‌بات تاریخچه گفتگو را ذخیره می‌کند؟

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

آیا می‌توان مدل GPT را با Claude جایگزین کرد؟

بله، اگر ارائه‌دهنده API مدل موردنظر را از طریق رابط سازگار ارائه کند، می‌توانید شناسه مدل را تغییر دهید. البته سازگاری قابلیت‌های موردنیاز باید بررسی شود.

جمع‌بندی

در این آموزش یاد گرفتیم چگونه با پایتون و API هوش مصنوعی یک چت‌بات ساده اما کاربردی بسازیم.

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

همچنین با نحوه تنظیم API Key، تغییر مدل، مدیریت مصرف توکن و رفع خطاهای رایج آشنا شدیم.

این پروژه می‌تواند پایه ساخت چت‌بات پشتیبانی، دستیار هوشمند یا سرویس گفتگوی اختصاصی باشد.

برای دسترسی به مدل‌های مختلف و دریافت API Key، می‌توانید از Sinox API استفاده کنید و تنظیمات اتصال را در مستندات رسمی بررسی کنید.