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

LangChain برای ساخت برنامه‌های مبتنی بر مدل زبانی، از زنجیره‌های ساده تا عامل‌ها و RAG، استفاده می‌شود. کلاس‌های ChatOpenAI و OpenAIEmbeddings آدرس پایه را به‌عنوان پارامتر می‌پذیرند، پس با تغییر همین آدرس به هوشوانا وصل می‌شوید و به همه‌ی مدل‌ها دسترسی دارید.

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

• مدل‌های OpenAI، Anthropic، Google، DeepSeek و دیگران با همان کلاس ChatOpenAI.
• embedding برای RAG با یک کلید.
• پرداخت ریالی و گزارش هزینه‌ی هر فراخوانی.

پیش‌نیازها

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

کلید را در متغیر محیطی نگه دارید و در کد ننویسید:

export HOOSHVANA_API_KEY="hv-YOUR_KEY"

راه‌اندازی در Python

pip install -U langchain-openai

import os
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

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

llm = ChatOpenAI(
    model="openai/gpt-4o-mini",
    base_url=API_BASE,
    api_key=API_KEY,
    temperature=0.3,
)

reply = llm.invoke("در یک جمله بگو RAG چیست.")
print(reply.content)

embeddings = OpenAIEmbeddings(
    model="openai/text-embedding-3-small",
    base_url=API_BASE,
    api_key=API_KEY,
    # Model ids with a vendor prefix are unknown to tiktoken; send raw text instead of token ids
    check_embedding_ctx_length=False,
)

vector = embeddings.embed_query("هوشوانا")
print(len(vector))  # 1536

پارامتر check_embedding_ctx_length=False مهم است. بدون آن، OpenAIEmbeddings سعی می‌کند متن را با tiktoken و بر اساس نام مدل به توکن تبدیل کند و چون نام openai/text-embedding-3-small برای tiktoken ناشناخته است، ممکن است خطا بگیرید یا آرایه‌ی توکن به‌جای متن فرستاده شود.

استریم و فراخوانی ابزار

for chunk in llm.stream("سه نکته برای نوشتن پرامپت خوب بگو."):
    print(chunk.content, end="", flush=True)

bind_tools و with_structured_output هم کار می‌کنند، به شرطی که مدل انتخابی function calling یا خروجی JSON را پشتیبانی کند.

راه‌اندازی در JavaScript و TypeScript

npm install @langchain/openai @langchain/core

import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";

const configuration = { baseURL: "https://hooshvana.ir/api/v1" };

const llm = new ChatOpenAI({
  model: "openai/gpt-4o-mini",
  apiKey: process.env.HOOSHVANA_API_KEY,
  configuration,
});

const reply = await llm.invoke("در یک جمله بگو RAG چیست.");
console.log(reply.content);

const embeddings = new OpenAIEmbeddings({
  model: "openai/text-embedding-3-small",
  apiKey: process.env.HOOSHVANA_API_KEY,
  configuration,
});

const vector = await embeddings.embedQuery("هوشوانا");
console.log(vector.length);

در نسخه‌ی جاوااسکریپت آدرس پایه داخل configuration.baseURL قرار می‌گیرد، نه در سطح بالای گزینه‌ها.

بررسی اتصال

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

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

اگر بعداً مدل embedding را عوض کردید، همه‌ی اسناد را دوباره embed کنید؛ بردارهای دو مدل با هم قابل مقایسه نیستند. شناسه‌ها نمونه هستند؛ فهرست کامل در کاتالوگ مدل‌ها است.

کنترل هزینه

• برای هر برنامه یا محیط (توسعه و تولید) کلید جدا بسازید.
• سقف خرج روزانه و ماهانه بگذارید، به‌خصوص برای عامل‌هایی که در حلقه اجرا می‌شوند.
• مدل‌های مجاز را به مدل‌های همان برنامه محدود کنید.
• max_tokens را در ChatOpenAI تنظیم کنید. هوشوانا پیش از اجرا بدترین حالت هزینه را با همین عدد برآورد می‌کند.
• اگر برنامه روی سرور ثابت اجرا می‌شود، IP آن را در فهرست IP مجاز کلید بگذارید.
• به‌جای ساختن vector store جداگانه، می‌توانید از پایگاه دانش هوشوانا استفاده کنید.

رفع اشکال

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