SDKها و زبانهای برنامهنویسی
اتصال به هوشوانا با SDKهای رسمی OpenAI در Python، Node.js، PHP و Go و با cURL، به همراه تنظیم متغیرهای محیطی OPENAI_BASE_URL و OPENAI_API_KEY.
آخرین بهروزرسانی:
هوشوانا SDK اختصاصی ندارد و لازم هم نیست. چون API آن با OpenAI و Anthropic سازگار است، SDKهای رسمی و کتابخانههای محبوب همین حالا با آن کار میکنند. فقط دو چیز را تنظیم میکنید: آدرس پایه و کلید API.
| تنظیم | مقدار |
|---|---|
| آدرس پایه (OpenAI) | https://hooshvana.ir/api/v1 |
| آدرس پایه (Anthropic SDK) | https://hooshvana.ir/api |
| کلید | کلید hv-... از داشبورد |
متغیرهای محیطی
بیشتر SDKها و ابزارهای سازگار با OpenAI، آدرس و کلید را از این متغیرها میخوانند:
export OPENAI_BASE_URL="https://hooshvana.ir/api/v1"
export OPENAI_API_KEY="$HOOSHVANA_API_KEY"با این تنظیم، SDKهای Python و Node.js بدون هیچ پارامتری به هوشوانا وصل میشوند:
from openai import OpenAI
client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEYاگر در همان سیستم با خود OpenAI هم کار میکنید، به جای متغیرهای سراسری، آدرس و کلید را صریحاً در کد بدهید تا اشتباهی پیش نیاید. برای SDKهای Anthropic متغیرهای معادل ANTHROPIC_BASE_URL و ANTHROPIC_API_KEY هستند.
Python
pip install openaiimport os
from openai import OpenAI
client = OpenAI(
base_url="https://hooshvana.ir/api/v1",
api_key=os.environ["HOOSHVANA_API_KEY"],
timeout=60,
max_retries=3,
)
resp = client.chat.completions.create(
model="openai/gpt-4o-mini",
messages=[{"role": "user", "content": "یک جملهی انگیزشی کوتاه بنویس."}],
)
print(resp.choices[0].message.content)برای برنامههای async از AsyncOpenAI استفاده کنید:
import asyncio
import os
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://hooshvana.ir/api/v1", api_key=os.environ["HOOSHVANA_API_KEY"])
async def main():
resp = await client.chat.completions.create(
model="google/gemini-2.5-flash",
messages=[{"role": "user", "content": "پایتخت ژاپن کجاست؟"}],
)
print(resp.choices[0].message.content)
asyncio.run(main())Node.js و TypeScript
npm install openaiimport OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://hooshvana.ir/api/v1",
apiKey: process.env.HOOSHVANA_API_KEY,
timeout: 60_000,
maxRetries: 3,
});
const resp = await client.chat.completions.create({
model: "openai/gpt-4o-mini",
messages: [{ role: "user", content: "یک جملهی انگیزشی کوتاه بنویس." }],
});
console.log(resp.choices[0].message.content);این کد را فقط در سمت سرور (Node.js، توابع سرور Next.js و مشابه) اجرا کنید. کلید نباید به مرورگر برسد. احراز هویت و کلیدها را ببینید.
PHP
کتابخانهی openai-php/client با Composer نصب میشود. برای تعیین آدرس پایه از factory استفاده کنید:
composer require openai-php/client guzzlehttp/guzzle<?php
require __DIR__ . '/vendor/autoload.php';
$client = OpenAI::factory()
->withApiKey(getenv('HOOSHVANA_API_KEY'))
->withBaseUri('https://hooshvana.ir/api/v1')
->make();
$response = $client->chat()->create([
'model' => 'openai/gpt-4o-mini',
'messages' => [
['role' => 'user', 'content' => 'سلام! یک نکتهی کوتاه دربارهی PHP بگو.'],
],
]);
echo $response->choices[0]->message->content . PHP_EOL;در Laravel میتوانید از بستهی openai-php/laravel استفاده کنید و در فایل .env مقدار OPENAI_API_KEY را کلید هوشوانا و OPENAI_BASE_URL را https://hooshvana.ir/api/v1 قرار دهید.
Go
کتابخانهی رسمی github.com/openai/openai-go آدرس پایه را با option.WithBaseURL میگیرد:
go get github.com/openai/openai-gopackage main
import (
"context"
"fmt"
"os"
"github.com/openai/openai-go"
"github.com/openai/openai-go/option"
)
func main() {
client := openai.NewClient(
option.WithBaseURL("https://hooshvana.ir/api/v1"),
option.WithAPIKey(os.Getenv("HOOSHVANA_API_KEY")),
)
resp, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
Model: "openai/gpt-4o-mini",
Messages: []openai.ChatCompletionMessageParamUnion{
openai.UserMessage("یک جمله دربارهی زبان Go بنویس."),
},
})
if err != nil {
panic(err)
}
fmt.Println(resp.Choices[0].Message.Content)
}امضای برخی توابع در نسخههای مختلف openai-go کمی فرق میکند. اگر کد بالا با نسخهی شما کامپایل نشد، مثالهای README همان نسخه را ببینید. تنظیم option.WithBaseURL در همهی نسخهها یکسان است.
cURL
برای آزمایش سریع یا زبانهایی که SDK ندارند، مستقیم HTTP بفرستید:
curl https://hooshvana.ir/api/v1/chat/completions \
-H "Authorization: Bearer $HOOSHVANA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "سلام"}]
}'هر زبانی که بتواند درخواست HTTPS با بدنهی JSON بفرستد، میتواند با هوشوانا کار کند. ساختار درخواست و پاسخ در Chat Completions آمده است.
SDKهای Anthropic
برای مدلهای Claude با API سازگار با Anthropic، از SDK رسمی Anthropic با آدرس پایهی https://hooshvana.ir/api استفاده کنید:
import os
import anthropic
client = anthropic.Anthropic(
base_url="https://hooshvana.ir/api",
api_key=os.environ["HOOSHVANA_API_KEY"],
)نمونههای کامل در Anthropic Messages API آمده است.
کتابخانهها و ابزارهای دیگر
هر ابزاری که امکان تعیین «OpenAI base URL» یا «OpenAI-compatible endpoint» را دارد، با هوشوانا کار میکند. چند نمونه:
- LangChain (Python): در
ChatOpenAIپارامترهایbase_urlوapi_keyرا تنظیم کنید. - LlamaIndex: از کلاس
OpenAILikeباapi_baseاستفاده کنید. - Vercel AI SDK: با
createOpenAI({ baseURL, apiKey })یک ارائهدهندهی سفارشی بسازید.
راهنمای ابزارهای کدنویسی و دستیارها مثل Claude Code و Codex CLI در بخش یکپارچهسازیها آمده است.
عیبیابی
| مشکل | علت احتمالی |
|---|---|
| خطای ۴۰۱ | کلید درست خوانده نشده؛ مقدار متغیر محیطی را چاپ و بررسی کنید (فقط چند نویسهی اول را) |
| خطای ۴۰۴ روی همهی درخواستها | آدرس پایه اشتباه است؛ برای SDKهای OpenAI باید به /v1 ختم شود |
model_not_found | شناسهی مدل بدون پیشوند سازنده نوشته شده؛ مثلاً gpt-4o-mini به جای openai/gpt-4o-mini |
| درخواستها به OpenAI میروند | متغیر OPENAI_BASE_URL در محیط اجرا تنظیم نشده یا SDK قدیمی آن را نمیخواند؛ آدرس را صریحاً در کد بدهید |
جدول کامل خطاها در خطاها و کدها آمده است.