راه‌اندازی LlamaIndex با کلاس OpenAILike برای چت و پرسش‌وپاسخ روی API پیکو هوش؛ همراه توضیح صادقانه درباره‌ی نبود embeddings.
پیکو هوش·انتشار: ·به‌روزرسانی: ·۵ دقیقه مطالعه
خلاصه: برای مدل‌های سازگار با OpenAI که اسم مدلشان در جدول داخلی LlamaIndex نیست، کلاس OpenAILike ساخته شده است. با آن می‌توانید مدل‌های چت پیکو هوش را به https://api.picoai.ir/v1 وصل کنید. هشدار صادقانه: پیکو هوش فعلاً اندپوینت embeddings ندارد؛ پس بخش «مدل چت» را با ما انجام دهید و مدل امبدینگ را جداگانه (مثلاً محلی) تأمین کنید.
import os
from llama_index.llms.openai_like import OpenAILike
llm = OpenAILike(
model="gpt-6-sol",
api_base="https://api.picoai.ir/v1",
api_key=os.environ["PICO_API_KEY"],
is_chat_model=True,
context_window=128000,
timeout=60,
)
print(llm.complete("کاربرد ایندکس در پایگاه داده را در یک جمله بگو."))
توضیح پارامترها:
api_base مسیر پایه است (با /v1).
is_chat_model=True باعث میشود از /chat/completions استفاده شود، که تنها مسیر متنی پیکو هوش است.
context_window را مطابق مدل انتخابی بدهید؛ مقدار هر مدل در صفحهی آن در کاتالوگ آمده است. عدد بالا فقط نمونه است؛ برای جلوگیری از ارسال متن بیش از حد، آن را محافظه‌کارانه تنظیم کنید.
چت و استریم
from llama_index.core.llms import ChatMessage
msgs = [
ChatMessage(role="system", content="به فارسی و مختصر پاسخ بده."),
ChatMessage(role="user", content="REST چیست؟"),
]
print(llm.chat(msgs))
for delta in llm.stream_chat(msgs):
print(delta.delta, end="", flush=True)
Claude Code را با متغیرهای ANTHROPIC_BASE_URL و کلید پیکو هوش روی اندپوینت سازگار با Anthropic (/v1/messages) اجرا کنید؛ مرحلهبهمرحله و با عیب‌یابی.
·
خبرنامه
آموزش‌ها و تغییرات جدید را به‌موقع بگیرید
فقط مطالب مفید درباره‌ی API هوش مصنوعی؛ بدون هرزنامه.
from llama_index.core import Settings
Settings.llm = llm
با این کار همه‌ی موتورهای کوئری از همین مدل استفاده می‌کنند.
محدودیت مهم: بدون embeddings
در RAG معمول دو مدل لازم است: امبدینگ (برای ایندکس و جستجو) و LLM (برای تولید پاسخ). پیکو هوش فقط مدل دوم را دارد. اگر Settings.embed_model را تنظیم نکنید، LlamaIndex به‌صورت پیش‌فرض سراغ OpenAI می‌رود و خطا می‌گیرید. راه‌حل‌ها:
امبدینگ محلی با HuggingFace:
pip install llama-index-embeddings-huggingface
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-m3")
مدل چندزبانه برای فارسی مناسب‌تر است. دانلود مدل و اجرای آن روی سرور خودتان انجام میشود، نه پیکو هوش.
بدون برداری: برای دیتاست کوچک از SummaryIndex یا جستجوی کلیدواژه (BM25) استفاده کنید که امبدینگ نمی‌خواهد.
یک RAG کوچک کامل
from llama_index.core import VectorStoreIndex, Document
docs = [
Document(text="پیکو هوش API سازگار با OpenAI ارائه می‌دهد."),
Document(text="درخواست ناموفق هزینه‌ای ندارد."),
]
index = VectorStoreIndex.from_documents(docs) # embed_model محلی
qe = index.as_query_engine(similarity_top_k=2)
print(qe.query("درخواست ناموفق چه هزینه‌ای دارد؟"))
اینجا مرحله‌ی برداری‌سازی با مدل محلی و تولید پاسخ با پیکو هوش انجام میشود. کیفیت پاسخ به تکه‌بندی (chunking) و کیفیت امبدینگ بستگی دارد.
هزینه
طول زمینه‌ای که LlamaIndex به مدل می‌فرستد (چند تکه + سوال) مستقیم روی توکن ورودی اثر می‌گذارد. similarity_top_k را کم نگه دارید و اندازه‌ی chunk را بهینه کنید. محاسبه‌ی دقیق: تخمین هزینه و توکن و قیمت‌ها.
عیب‌یابی
علامت
علت
راه‌حل
خطا درباره‌ی OPENAI_API_KEY هنگام ایندکس
embed_model پیش‌فرض OpenAI است
Settings.embed_model را محلی کنید
Unknown model
استفاده از OpenAI به‌جای OpenAILike
کلاس OpenAILike
404
api_base بدون /v1
نشانی را اصلاح کنید
پاسخ بریده
max_tokens کم
پارامتر را زیاد کنید
401
کلید نامعتبر
کلید را بازبینی کنید
مدل‌های دیگر و نکات انتخاب
چون OpenAILike مدل را در جدول داخلی جستجو نمی‌کند، می‌توانید هر شناسه‌ی کاتالوگ را بدهید؛ مثلاً model="claude-sonnet-5-5" یا model="deepseek-v4-pro". برای هر مدل، سه چیز را بررسی کنید: اندازه‌ی زمینه، قیمت ورودی و خروجی، و پشتیبانی از ویژگی‌های مورد نیاز مثل بینایی. اطلاعات هر مدل در صفحهی اختصاصی آن (مثل claude-sonnet-5-5) آمده است.
اگر از ایجنت LlamaIndex با ابزار (FunctionAgent/ReActAgent) استفاده می‌کنید، برای فعال‌شدن function calling در OpenAILike پارامتر is_function_calling_model=True را بدهید و مدلی را انتخاب کنید که واقعاً از ابزار پشتیبانی می‌کند. اگر مطمئن نیستید، ابتدا با ReAct (مبتنی بر متن) شروع کنید و رفتار را آزمایش کنید. جزئیات پروتکل ابزار در راهنمای Function Calling آمده است.
الگوی توصیه‌شده برای تولید
۱. اسناد را یک‌بار با امبدینگ محلی ایندکس و روی دیسک ذخیره کنید (index.storage_context.persist()). ۲. در زمان اجرا فقط ایندکس را بارگذاری کنید تا هر درخواست امبدینگ سنگین نداشته باشد. ۳. پرامپت سیستم را صریح بنویسید: «فقط بر اساس متن داده‌شده پاسخ بده و اگر پاسخ در متن نیست بگو نمی‌دانم». ۴. تعداد تکه‌های بازیابی‌شده را محدود کنید تا هزینه‌ی توکن ورودی کنترل شود. ۵. خطاهای 429 و 503 را با تلاش مجدد نمایی مدیریت کنید؛ راهنمای خطاها.
تفاوت complete و chat
متد complete یک رشته می‌گیرد و آن را به یک پیام کاربر تبدیل می‌کند، اما chat فهرست پیام با نقش‌ها می‌گیرد و برای گفتگوی چندنوبتی مناسب‌تر است. در هر دو حالت، درخواست نهایی به مسیر /chat/completions می‌رود چون is_chat_model=True است.
عیب‌یابی با لاگ
برای دیدن درخواست‌ها، لاگ‌گیری LlamaIndex را فعال کنید:
یا از callback دیباگ استفاده کنید تا پرامپت نهایی و تکه‌های بازیابی‌شده را ببینید. اغلب مشکلات کیفیت RAG از تکه‌بندی نامناسب یا بازیابی بی‌ربط است، نه مدل.
سوالات متداول
آیا میتوانم از OpenAIEmbedding با پیکو هوش استفاده کنم؟
خیر؛ اندپوینت embeddings وجود ندارد. از مدل محلی یا سرویس دیگری استفاده کنید.
کدام مدل برای RAG فارسی مناسب است؟
چند مدل از کاتالوگ را روی نمونهی سوالهای واقعی خودتان بسنجید؛ claude-sonnet-5-5 و gpt-6-sol گزینههای رایجاند.