getting-started.md

Getting started

FerryAI runs ONNX, GGUF and RubixML models directly in PHP via FFI — no Python, no HTTP sidecars. This guide gets you from install to a first embedding and chat.

Requirements

• PHP 8.3+ with ext-ffi, ext-json, ext-hash, ext-fileinfo.
• Optional native libraries / models per capability — see the Dependencies & downloads matrix.

Install

composer require ferry-ai/php-inference

Configure

Everything goes through the FerryAI\AI facade after a one-time config():

use FerryAI\AI;

AI::config([
    'backend' => 'onnx',           // default task backend: onnx | llama | cpu
    'device'  => 'cpu',            // cpu | cuda | auto
    'backends' => [
        'embedding' => ['model_path' => '/path/to/all-MiniLM-L6-v2-onnx'],
        'llama'     => ['model_path' => '/path/to/model.gguf'],
    ],
]);

See configuration for every key.

First embedding

$vec = AI::embed('Hello world');   // EmbeddingResult
echo $vec->dimension;              // 384
$sim = AI::similarity('cat', 'kitten');   // 0.79

Requires ONNX Runtime + an embedding model — see backends/onnx and embedding.

First chat

$reply = AI::chat([
    ['role' => 'user', 'content' => 'What is the capital of France?'],
]);
echo $reply->text;                 // "The capital of France is Paris."

Requires the ferry_llama wrapper + a GGUF model — see backends/llama and streaming.

Next steps

• Vector store — store and search embeddings (SQLite / PostgreSQL).
• Pipeline — compose embed → store → search stages.
• Model hub — download & verify models from HuggingFace.
• Troubleshooting — when something does not load.
• Runnable examples: examples/.