اتصال LlamaIndex به هوشوانا

LlamaIndex فریم‌ورکی برای ساخت RAG و عامل‌های داده‌محور است. کلاس‌های پیش‌فرض OpenAI در LlamaIndex فقط نام مدل‌های رسمی OpenAI را می‌شناسند، پس برای هوشوانا که مدل‌ها را با شناسه‌ی vendor/model نام‌گذاری می‌کند، از کلاس‌های «OpenAI-like» استفاده می‌کنیم.

چه چیزی به دست می‌آورید

• مدل‌های چند سازنده در LlamaIndex با یک کلید.
• embedding برای ایندکس‌سازی اسناد.
• پرداخت ریالی و گزارش هزینه‌ی هر مرحله.

پیش‌نیازها

1. حساب کاربری در هوشوانا.
2. یک کلید API از صفحه‌ی کلیدها.
3. اعتبار کافی در کیف پول.
4. Python 3.9 به بالا.

pip install -U llama-index-core llama-index-llms-openai-like llama-index-embeddings-openai-like
export HOOSHVANA_API_KEY="hv-YOUR_KEY"

راه‌اندازی

مدل زبانی با OpenAILike

import os
from llama_index.llms.openai_like import OpenAILike

API_BASE = "https://hooshvana.ir/api/v1"
API_KEY = os.environ["HOOSHVANA_API_KEY"]

llm = OpenAILike(
    model="openai/gpt-4o-mini",
    api_base=API_BASE,
    api_key=API_KEY,
    is_chat_model=True,
    is_function_calling_model=True,
    context_window=128000,
    max_tokens=1024,
)

print(llm.complete("در یک جمله بگو LlamaIndex چه کاری می‌کند."))

is_chat_model=True لازم است تا LlamaIndex به /chat/completions درخواست بفرستد، نه به /completions که هوشوانا ارائه نمی‌دهد. context_window را مطابق مدل انتخابی از کاتالوگ مدل‌ها بگذارید؛ LlamaIndex از این عدد برای تقسیم زمینه استفاده می‌کند. اگر مدل function calling را پشتیبانی نمی‌کند، is_function_calling_model را False بگذارید.

embedding

کلاس OpenAIEmbedding از پکیج llama-index-embeddings-openai پارامتر api_base را می‌پذیرد، اما در بسیاری از نسخه‌ها نام مدل را با فهرست مدل‌های رسمی OpenAI مقایسه می‌کند و شناسه‌ای مثل openai/text-embedding-3-small را رد می‌کند. راه مطمئن، کلاس OpenAILikeEmbedding است:

from llama_index.embeddings.openai_like import OpenAILikeEmbedding

embed_model = OpenAILikeEmbedding(
    model_name="openai/text-embedding-3-small",
    api_base=API_BASE,
    api_key=API_KEY,
    embed_batch_size=32,
)

print(len(embed_model.get_text_embedding("هوشوانا")))  # 1536

ساخت ایندکس و پرس‌وجو

from llama_index.core import Settings, SimpleDirectoryReader, VectorStoreIndex

Settings.llm = llm
Settings.embed_model = embed_model

documents = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(documents)

query_engine = index.as_query_engine(similarity_top_k=5)
print(query_engine.query("مهم‌ترین نکته‌ی این اسناد چیست؟"))

تنظیم Settings.llm و Settings.embed_model مهم است. اگر یکی از آن‌ها را تنظیم نکنید، LlamaIndex سراغ OpenAI پیش‌فرض می‌رود و با خطای کلید یا اتصال مواجه می‌شوید.

بررسی اتصال

کد بالا را اجرا کنید. اگر پاسخ متنی و طول بردار 1536 چاپ شد، اتصال درست است. در گزارش‌ها درخواست‌های /chat/completions و /embeddings را با هزینه‌شان می‌بینید.

مدل‌های پیشنهادی

شناسه‌ها نمونه هستند؛ فهرست کامل در کاتالوگ مدل‌ها است.

کنترل هزینه

• ایندکس‌سازی اولیه بیشترین درخواست embedding را می‌سازد. ایندکس را با index.storage_context.persist() ذخیره کنید تا در هر اجرا دوباره ساخته نشود.
• برای محیط توسعه و تولید کلیدهای جدا بسازید و برای هر کدام سقف خرج روزانه بگذارید.
• مدل‌های مجاز و نقطه‌های پایانی مجاز (chat و embeddings) را محدود کنید.
• max_tokens را تنظیم کنید؛ هوشوانا پیش از اجرا بدترین حالت هزینه را با همین عدد برآورد می‌کند.
• اگر نمی‌خواهید خودتان ایندکس را نگه دارید، پایگاه دانش هوشوانا همین کار را در داشبورد انجام می‌دهد.

رفع اشکال

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