PHPackages                             amirkateb/laravel-ai-suite - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. amirkateb/laravel-ai-suite

ActiveLibrary[Utility & Helpers](/categories/utility)

amirkateb/laravel-ai-suite
==========================

Unified AI suite for Laravel with multi-provider drivers, fallback, dynamic model listing, pricing, chat, OCR, embeddings, images, audio, tools, and fine-tuning.

v1.0.2(7mo ago)07MITPHPPHP >=8.1

Since Oct 6Pushed 7mo agoCompare

[ Source](https://github.com/amirkateb/laravel-ai-suite)[ Packagist](https://packagist.org/packages/amirkateb/laravel-ai-suite)[ RSS](/packages/amirkateb-laravel-ai-suite/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (3)Versions (4)Used By (0)

پکیج جامع اتصال به هوش‌های مصنوعی برای لاراول)

[English](README.en.md) • [العربية](README.ar.md)

**نگهدارنده:** [@amirkateb](https://github.com/amirkateb)
**حداقل نسخه PHP:** 8.1 • **فریم‌ورک:** Laravel 9+

این پکیج یک لایه‌ی یکپارچه برای کار با چندین ارائه‌دهندهٔ هوش مصنوعی فراهم می‌کند: OpenAI، Google Gemini، DeepSeek، xAI Grok، Anthropic، Azure OpenAI، AWS Bedrock و Ollama (لوکال). امکانات کلیدی:

- انتخاب درایور پیش‌فرض و زنجیره‌ی fallback
- فهرست داینامیک مدل‌ها از هر سرویس
- چت (messages)، ابزارها (function/tool calls)، تع嵌‌گذاری (embeddings)
- OCR از طریق مدل‌های vision/chat، تولید تصویر، STT و TTS
- فاین‌تیونینگ (در سرویس‌هایی که پشتیبانی دارند)
- محاسبه‌ی هزینه‌ی هر درخواست بر اساس قیمت مدل‌ها (DB + JSON)
- لاگ کامل دیتابیسی برای هر فراخوانی
- مثال‌های کامل بدون روت (فقط برای برنامه‌نویسان)

---

نصب
---

[](#نصب)

```
composer require amirkateb/laravel-ai-suite
php artisan vendor:publish --provider="AmirKateb\AiSuite\Providers\AiSuiteServiceProvider" --tag=config
php artisan vendor:publish --provider="AmirKateb\AiSuite\Providers\AiSuiteServiceProvider" --tag=migrations
php artisan vendor:publish --provider="AmirKateb\AiSuite\Providers\AiSuiteServiceProvider" --tag=seeders
php artisan migrate
php artisan ai:seed-pricing

```

> اگر از فایل‌های قیمت JSON داخلی استفاده می‌کنید و می‌خواهید کامل‌ترین پوشش را داشته باشید، از Seeder «کامل» استفاده کنید:

```
php artisan db:seed --class="AmirKateb\AiSuite\Database\Seeders\AiSuiteFullPricingSeeder"

```

---

تنظیمات
-------

[](#تنظیمات)

پس از publish، فایل `config/ai.php` ایجاد می‌شود. پارامترهای کلیدی:

- `default`: نام درایور پیش‌فرض (مثلاً `openai`)
- `fallback.enabled`: فعال/غیرفعال بودن زنجیره‌ی جایگزین
- `fallback.order`: ترتیب ارائه‌دهنده‌ها برای تلاش مجدد
- `providers`: کلیدها و تنظیمات هر سرویس (API key، base\_url، قیمت‌های دستی)

نمونه `.env`:

```
# =========================
# AI Suite — Core Settings
# =========================
AI_DEFAULT=openai

# Fallback
AI_FALLBACK_ENABLED=false
AI_FALLBACK_ORDER=openai,google_gemini,deepseek,xai_grok,ollama,anthropic,azure_openai,aws_bedrock

# Conversation history limits
AI_HISTORY_MAX_MESSAGES=50
AI_HISTORY_MAX_TOKENS=32000

# Costing
AI_COST_CURRENCY=USD
AI_COST_ENABLED=true

# Timeouts (seconds)
AI_TIMEOUT_CONNECT=10
AI_TIMEOUT_READ=120

# Retries
AI_RETRY_ENABLED=true
AI_RETRY_TIMES=2
AI_RETRY_SLEEP_MS=250

# =========================
# OpenAI
# =========================
OPENAI_ENABLED=true
OPENAI_API_KEY=sk-xxxxx
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_ORG=
OPENAI_PROJECT=
OPENAI_MODELS_TTL=3600

# =========================
# Google Gemini
# =========================
GEMINI_ENABLED=true
GEMINI_API_KEY=AIzaSyxxxxx
GEMINI_BASE_URL=https://generativelanguage.googleapis.com
GEMINI_MODELS_TTL=3600

# =========================
# DeepSeek
# =========================
DEEPSEEK_ENABLED=true
DEEPSEEK_API_KEY=ds-xxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODELS_TTL=3600

# =========================
# xAI Grok
# =========================
XAI_ENABLED=true
XAI_API_KEY=xai-xxxxx
XAI_BASE_URL=https://api.x.ai
XAI_MODELS_TTL=3600

# =========================
# Ollama (local)
# =========================
OLLAMA_ENABLED=true
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODELS_TTL=60

# =========================
# Anthropic
# =========================
ANTHROPIC_ENABLED=true
ANTHROPIC_API_KEY=sk-ant-xxxxx
ANTHROPIC_BASE_URL=https://api.anthropic.com
ANTHROPIC_MODELS_TTL=3600

# =========================
# Azure OpenAI
# =========================
AZURE_OPENAI_ENABLED=false
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT= # e.g. https://your-resource.openai.azure.com
AZURE_OPENAI_DEPLOYMENT= # e.g. gpt-4o
AZURE_OPENAI_API_VERSION=2024-06-01
AZURE_OPENAI_MODELS_TTL=3600

# =========================
# AWS Bedrock
# =========================
BEDROCK_ENABLED=false
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
BEDROCK_MODELS_TTL=3600

```

---

دیتابیس
-------

[](#دیتابیس)

### جداول

[](#جداول)

- `ai_suite_logs`: ثبت کامل هر فراخوانی شامل provider، مدل، وضعیت، مدت‌زمان، توکن‌های مصرفی، هزینه، payload درخواست/پاسخ.
- `ai_suite_model_prices`: قیمت‌ مدل‌ها برای محاسبه‌ی هزینه.

### Migration‌ها

[](#migration‌ها)

پس از publish و اجرای `php artisan migrate` دو جدول بالا ساخته می‌شود. تاریخچه و ایندکس‌ها برای کوئری‌گیری سریع لحاظ شده‌اند.

### Seeders قیمت‌ها

[](#seeders-قیمت‌ها)

- `AiSuitePricingSeeder`: نمونه‌ی مینیمال.
- `AiSuiteFullPricingSeeder`: تمام مدل‌های اصلی را از JSON داخلی می‌خواند.
- فرمان اختصاصی: `php artisan ai:seed-pricing`

### JSON قیمت‌ها

[](#json-قیمت‌ها)

مسیر: `vendor/amirkateb/laravel-ai-suite/src/Resources/pricing/*.json`
برای هر provider یک فایل JSON شامل آرایه‌ای از رکوردها با کلیدهای:

- `provider`, `model`, `input_per_1m`, `output_per_1m`, `cached_input_per_1m|null`, `unit` (پیش‌فرض 1,000,000), `currency`, `source`

Seeding کامل از این فایل‌ها توسط `AiSuiteFullPricingSeeder` انجام می‌شود.

---

استفاده (بدون روت؛ مخصوص برنامه‌نویس‌ها)
----------------------------------------

[](#استفاده-بدون-روت-مخصوص-برنامه‌نویس‌ها)

### Service Resolution

[](#service-resolution)

```
use AmirKateb\AiSuite\AiManager;

$ai = app(AiManager::class);       // یا helper: ai()
$ai->driver('openai');             // تغییر درایور فعال
```

### فهرست مدل‌ها

[](#فهرست-مدل‌ها)

```
$modelsDefault = $ai->listModels();
$modelsOpenAI = $ai->listModels('openai');
```

### چت ساده

[](#چت-ساده)

```
$resp = $ai->chat([
  ['role' => 'system', 'content' => 'You are helpful.'],
  ['role' => 'user', 'content' => 'سلام!']
], ['model' => 'gpt-4o-mini']);
```

### چت با ابزارها (function/tool calls)

[](#چت-با-ابزارها-functiontool-calls)

```
$tools = [[
  'type' => 'function',
  'function' => [
    'name' => 'get_time',
    'description' => 'returns current time',
    'parameters' => ['type' => 'object', 'properties' => []]
  ]
]];
$resp = $ai->chat([['role'=>'user','content'=>'الان ساعت چند است؟']], ['model'=>'gpt-4o','tools'=>$tools]);
```

### Embeddings

[](#embeddings)

```
$resp = $ai->embeddings('متن برای تع嵌‌گذاری', ['model' => 'text-embedding-3-small']);
```

### OCR (Vision از مسیر تصویر لوکال)

[](#ocr-vision-از-مسیر-تصویر-لوکال)

```
$resp = $ai->ocr(storage_path('app/public/sample.png'), ['model' => 'gpt-4o-mini', 'prompt' => 'متن قابل خواندن را استخراج کن']);
```

### تولید تصویر

[](#تولید-تصویر)

```
$resp = $ai->image(['model' => 'gpt-image-1', 'prompt' => 'a blue cat', 'size' => '1024x1024', 'n' => 1]);
```

### تبدیل گفتار به متن (STT)

[](#تبدیل-گفتار-به-متن-stt)

```
$resp = $ai->audioToText(storage_path('app/sample.mp3'), ['model' => 'gpt-4o-transcribe']);
```

### تبدیل متن به گفتار (TTS)

[](#تبدیل-متن-به-گفتار-tts)

```
$resp = $ai->textToAudio('سلام دنیا', ['model' => 'gpt-4o-mini-tts', 'voice' => 'alloy', 'format' => 'mp3']);
```

### فاین‌تیونینگ

[](#فاین‌تیونینگ)

```
$resp = $ai->driver('openai')->fineTune([
  'training_file' => 'file-xxxx',
  'model' => 'gpt-4o-mini',
  'hyperparameters' => []
]);
```

### محاسبه‌ی هزینه

[](#محاسبه‌ی-هزینه)

```
use AmirKateb\AiSuite\Support\UsageCalculator;

$resp = $ai->chat([['role'=>'user','content'=>'یک جواب کوتاه بده']], ['model' => 'gpt-4o-mini']);
$usage = UsageCalculator::parse('openai', $resp, ['model' => 'gpt-4o-mini']);
$cost = $ai->calculateCost($usage);
// $cost بر حسب currency تنظیم‌شده در config('ai.costing.currency')
```

### مثال‌های آماده (بدون روت)

[](#مثال‌های-آماده-بدون-روت)

در `src/Examples` کلاس‌های `UsageExamples` و `FineTuneExamples` را می‌توانید داخل Tinker اجرا کنید:

```
php artisan tinker
>>> AmirKateb\AiSuite\Examples\UsageExamples::runAll();

```

---

لاگ کامل
--------

[](#لاگ-کامل)

هر فراخوانی از طریق `AiManager` در جدول `ai_suite_logs` ثبت می‌شود:

- شناسهٔ درخواست، کاربر (در صورت Auth)، IP، زمان شروع/پایان، مدت، وضعیت
- ورودی/خروجی توکن‌ها و هزینه
- Payload درخواست و پاسخ (برای دیباگ)

برای خاموش‌کردن لاگینگ کافی است به‌جای `AiManager` پکیج، از یک wrapper خودتان استفاده کنید یا مدل `AiLog` را override کنید.

---

امنیت
-----

[](#امنیت)

- هیچ Route نمونه‌ای به‌صورت پیش‌فرض فعال نیست.
- مثال‌ها فقط در Tinker/کُد اپلیکیشن استفاده می‌شوند.
- ورودی فایل‌ها را در مسیرهای امن خوانده و سایز فایل‌های صوت/تصویر را کنترل کنید.
- برای محیط Production، نرخ درخواست‌ها، timeouts و fallback را مطابق SLA تنظیم کنید.

---

توسعه
-----

[](#توسعه)

- افزودن درایور جدید: یک کلاس پیاده‌سازی `Contracts\DriverInterface` بنویسید و در `config('ai.drivers.map')` ثبت کنید.
- سفارشی‌سازی قیمت‌ها: رکوردهای جدول `ai_suite_model_prices` را به‌روزرسانی یا JSONهای `src/Resources/pricing` را ویرایش و مجدد seed کنید.
- تاریخچه مکالمه: اگر نیاز به استوری پایدار دارید، `HistoryStoreInterface` را به‌دلخواه پیاده‌سازی کنید.

---

لایسنس
------

[](#لایسنس)

MIT — (c) 2025, [@amirkateb](https://github.com/amirkateb)

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance64

Regular maintenance activity

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

219d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c5d4a2845cb6cedddfe5d01668c31e1291202f30a7382245d9f0974a41dbcaf9?d=identicon)[amirkateb](/maintainers/amirkateb)

---

Top Contributors

[![amirkateb](https://avatars.githubusercontent.com/u/56022242?v=4)](https://github.com/amirkateb "amirkateb (73 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/amirkateb-laravel-ai-suite/health.svg)

```
[![Health](https://phpackages.com/badges/amirkateb-laravel-ai-suite/health.svg)](https://phpackages.com/packages/amirkateb-laravel-ai-suite)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[orchestra/canvas

Code Generators for Laravel Applications and Packages

21017.2M158](/packages/orchestra-canvas)[illuminate/pipeline

The Illuminate Pipeline package.

9446.6M213](/packages/illuminate-pipeline)[illuminate/pagination

The Illuminate Pagination package.

10532.5M862](/packages/illuminate-pagination)[spatie/laravel-pjax

A pjax middleware for Laravel 5

513371.8k11](/packages/spatie-laravel-pjax)[spatie/laravel-mix-preload

Add preload and prefetch links based your Mix manifest

169176.0k2](/packages/spatie-laravel-mix-preload)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)