آموزش LangChain با Base URL سفارشی و API پیکو هوش

نکته‌ها:

• model باید دقیقاً یکی از شناسه‌های کاتالوگ مدل‌ها باشد؛ مثلاً gpt-6-sol، claude-sonnet-5-5 یا deepseek-v4-pro.
• پارامتر base_url همان openai_api_base قدیمی است. هر دو نام پذیرفته می‌شوند و مقدار صریح، بر متغیرهای محیطی اولویت دارد. اگر نسخه‌ی خیلی قدیمی LangChain دارید، بسته را به‌روز کنید.
• max_retries تلاش مجدد خودکار برای خطاهای شبکه و ۵xx را انجام می‌دهد؛ جزئیات در راهنمای خطاها و Retry.

گام ۴: پرامپت و زنجیره

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "تو یک دستیار فنی هستی و فارسی روان و کوتاه پاسخ می‌دهی."),
    ("human", "{question}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"question": "REST و GraphQL را مقایسه کن."}))

ساختار prompt | llm | parser همان LCEL است که در مقاله‌ی LCEL و استریم عمیق‌تر بررسی شده است.

گام ۵: تعویض مدل بدون تغییر معماری

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

MODEL = os.getenv("PICO_MODEL", "gpt-6-luna")
llm = ChatOpenAI(model=MODEL, base_url="https://api.picoai.ir/v1",
                 api_key=os.environ["PICO_API_KEY"])

برای کارهای ساده و پرتکرار از مدل‌های اقتصادی (مثل claude-haiku-5-5) و برای استدلال سنگین از مدل‌های قوی‌تر استفاده کنید. مشخصات هر مدل در صفحه‌ی claude-sonnet-5-5 و gpt-6-sol آمده است.

چه چیزی پشتیبانی می‌شود و چه چیزی نه

پیکو هوش فعلاً روی مسیر /v1/chat/completions (چت، استریم) تمرکز دارد. اندپوینت embeddings ارائه نمی‌شود؛ بنابراین OpenAIEmbeddings را به پیکو هوش وصل نکنید. اگر RAG می‌سازید، مدل امبدینگ را از منبع دیگری تهیه کنید و فقط تولید پاسخ را با پیکو هوش انجام دهید.

عیب‌یابی

تنظیمات پیشرفته ChatOpenAI

چند پارامتر که در پروژه‌های واقعی مفیدند:

llm = ChatOpenAI(
    model="claude-sonnet-5-5",
    base_url="https://api.picoai.ir/v1",
    api_key=os.environ["PICO_API_KEY"],
    max_tokens=800,        # سقف طول پاسخ؛ هزینه‌ی خروجی را کنترل می‌کند
    top_p=0.9,
    streaming=False,
    default_headers={"X-App": "my-service"},  # برچسب دلخواه برای لاگ خودتان
)

• max_tokens مهم‌ترین اهرم کنترل هزینه است؛ بدون آن مدل ممکن است پاسخ بلند بنویسد.
• timeout را برای مدل‌های استدلالی بیشتر (مثلاً ۱۲۰ ثانیه) بگذارید.
• برای محیط‌های سازمانی با پروکسی، http_client سفارشی (httpx) می‌توانید بدهید.

اتصال از طریق متغیرهای محیطی

اگر نمی‌خواهید base_url را در کد بنویسید، کتابخانه‌ی OpenAI متغیرهای OPENAI_API_KEY و OPENAI_BASE_URL را می‌خواند:

export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://api.picoai.ir/v1"

سپس ChatOpenAI(model="gpt-6-sol") بدون آرگومان اضافی کار می‌کند. طبق مستندات LangChain ترتیب اولویت این است: آرگومان base_url، سپس OPENAI_API_BASE (خوانده‌شده توسط LangChain) و بعد OPENAI_BASE_URL (خوانده‌شده توسط SDK اوپن‌ای‌آی)؛ با OPENAI_BASE_URL گزارش usage در استریم به‌طور پیش‌فرض خاموش می‌ماند (stream_usage را اگر لازم دارید صریحاً True بدهید). این روش برای استقرار با Docker و CI راحت است. فقط مطمئن شوید این متغیرها برای ابزار دیگری که واقعاً به OpenAI وصل است تداخل ایجاد نمی‌کنند.

چک‌لیست قبل از انتشار

1. کلید در متغیر محیطی یا مدیر اسرار نگهداری شود، نه در کد.
2. برای هر کلید سقف درخواست در دقیقه و سقف ماهانه تعریف شود.
3. max_retries و timeout مشخص باشد.
4. خطای 402 (کمبود موجودی) در برنامه مدیریت و به کاربر یا تیم اطلاع داده شود.
5. مصرف توکن از usage_metadata لاگ شود تا هزینه‌ها قابل پیگیری باشد.

هشدار سازگاری

مستندات رسمی LangChain تصریح می‌کند ChatOpenAI فقط مشخصات رسمی API اوپن‌ای‌آی را هدف می‌گیرد و فیلدهای غیراستاندارد پاسخ (مثل reasoning_content) استخراج یا حفظ نمی‌شوند. برای چت، استریم و ابزار معمولی کافی است، اما اگر به فیلدهای اختصاصی یک مدل نیاز دارید، پاسخ خام را بررسی کنید.

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

آیا باید حتماً از ChatOpenAI استفاده کنم؟

بله؛ برای هر API سازگار با OpenAI همین کلاس مناسب است و تنها با base_url به پیکو هوش می‌رسد. مدل‌های Claude را هم می‌توان از همین مسیر با شناسه‌ی claude-sonnet-5-5 صدا زد.

درخواست ناموفق هزینه دارد؟

خیر. هزینه ابتدا رزرو و پس از موفقیت تسویه می‌شود؛ درخواست ناموفق بدون کسر هزینه است. توضیح کامل در مقاله‌ی محاسبه‌ی هزینه.

آیا embeddings پشتیبانی می‌شود؟

خیر، در حال حاضر فقط مدل‌های چت و موارد ذکرشده در مستندات در دسترس هستند.

صفحه‌ی راهنمای اختصاری هم دارید؟

بله، صفحه‌ی اتصال LangChain خلاصه‌ی تنظیمات را دارد.