DEV Community: Samuel Akopyan

Векторы, размерности и пространства признаков

Samuel Akopyan — Mon, 11 May 2026 16:46:01 +0000

Если убрать из машинного обучения все сложные слова и модные термины, то в сухом остатке почти всегда останется одна и та же идея: мы представляем реальные объекты числами и работаем с этими числами математически. Именно здесь на сцену выходят векторы, размерности и пространства признаков. Как PHP-разработчикам вам особенно важно понять это интуитивно, а не формально, потому что в коде вы постоянно будете иметь дело не с абстрактной линейной алгеброй, а с массивами чисел, матрицами и операциями над ними.

Вектор как способ описать объект

Вектор в контексте машинного обучения – это просто упорядоченный набор чисел. Каждое число описывает какой-то аспект объекта. Если объект простой, вектор короткий. Если объект сложный, вектор может быть очень длинным.

Представим пользователя интернет-магазина. Мы можем описать его так: возраст, количество покупок за год, средний чек. Тогда один пользователь – это вектор из трех чисел:

(возраст, покупки, средний чек)

В PHP это будет выглядеть максимально приземленно:

$userVector = [35, 12, 78.5];

Важно понять: вектор – это не просто массив. Порядок элементов имеет смысл. Если вы перепутаете местами возраст и средний чек, модель не "догадается", что вы имели в виду. Для нее это будут другие данные.

Размерность вектора

Размерность вектора – это количество чисел в нем. В примере выше размерность равна 3. Если вы добавите еще один признак, например, "дней с последней покупки", размерность станет 4.

Размерность напрямую связана с тем, насколько подробно вы описываете объект. Низкая размерность означает грубое описание, высокая – более детальное. Но высокая размерность не всегда лучше. Каждый дополнительный признак – это новая степень свободы для модели и в то же время новый источник шума.

Для лучшего понимания, полезно думать о размерности как о фиксированном контракте. Если модель ожидает вектор длины 10, вы обязаны всегда передавать ровно 10 чисел, в одном и том же порядке.

function predict(array $features): float {
    if (count($features) !== 10) {
        throw new InvalidArgumentException("Ожидается вектор размерности 10");
    }

    // дальнейшие вычисления
}

Пример:

$features = [0.12, 0.85, 0.33, 0.67, 0.91, 0.44, 0.58, 0.76, 0.29, 0.50];

try {
    $result = predict($features);
    echo "Скор модели: " . round($result, 3) . "\n";

    // Интерпретация результата
    if ($result > 0.7) {
        echo "Высокая вероятность положительного исхода";
    } elseif ($result > 0.4) {
        echo "Средняя вероятность";
    } else {
        echo "Низкая вероятность";
    }
} catch (Exception $e) {
    echo "Ошибка: " . $e->getMessage();
}

// Скор модели: 0.75
// Высокая вероятность положительного исхода

Пространство признаков

Формально пространство признаков обычно обозначают как как $R^n$ , что означает, что каждый объект описывается вектором $x = (x ₁, x ₂, \dots, x ₙ)$ из $n$ вещественных чисел, а совокупность всех таких векторов образует единое абстрактное пространство. Именно в этом $n$ -мерном пространстве "живут" данные, с которыми работают большинство моделей машинного обучения: в нём определены операции сложения векторов и умножения на число, что позволяет применять инструменты линейной алгебры. И хотя в практическом машинном обучении формальные аксиомы отходят на второй план, критически важно понимать, что любая модель всегда функционирует внутри фиксированного пространства, заданного структурой входных признаков.

Если размерность равна 2, пространство признаков – это обычная плоскость. Если 3 – привычное трехмерное пространство. Если больше, то визуализировать его уже фактически невозможно, но математически это то же самое пространство $R^n$ .

Каждая точка в этом пространстве – это один объект из реального мира, переведенный на язык чисел. Пользователь, товар, документ, изображение – все они после подготовки данных становятся точками в пространстве признаков.

Пространство признаков – это среда, в которой работает алгоритм машинного обучения. Всё, что раньше было строками, датами, категориями и JSON, после "feature engineering" превращается в чистую математику – набор чисел.

Признаки как оси координат

Каждый признак – это отдельная ось координат в пространстве. Математически это означает, что значение признака $x ᵢ$ – это координата точки вдоль $i$ -й оси.

Например, вектор (35, 12, 78.5) – это точка в трехмерном пространстве, где первая ось – возраст, вторая – количество покупок, третья – средний чек.

Это сразу объясняет несколько важных вещей.

Во-первых, признаки должны быть сопоставимы по масштабу (ещё одна причина, почему мы используем преобразование признаков в числа). Если одна ось измеряется в десятках, а другая – в сотнях тысяч, то расстояния и углы, вычисляемые выбранной метрикой, перестают отражать реальное сходство объектов.

Во-вторых, добавление нового признака – это добавление новой оси. Пространство становится более размерным (плюс ещё один размер), а каждая точка получает еще одну координату. Модель вынуждена учитывать еще одно направление при принятии решений.

Нормализация и масштабирование

На практике почти всегда приходится приводить признаки к сопоставимым масштабам по порядку величины. Это можно сделать разными способами: нормализацией (приведение значений к фиксированному диапазону, например от 0 до 1) или стандартизацией (приведение распределения к нулевому среднему и единичному стандартному отклонению). Оба подхода решают одну и ту же инженерную задачу – сделать признаки сопоставимыми для алгоритма.

В зависимости от свойств данных могут применяться логарифмические и другие нелинейные преобразования масштаба, однако их рассмотрение выходит за рамки данной книги.

Нужно понять, что использование нормализации и масштабирования не прихоть математиков, а чисто инженерная необходимость, так как большинство алгоритмов машинного обучения чувствительны к масштабу входных данных: признаки с большими числовыми значениями начинают доминировать над остальными, искажая вклад действительно информативных признаков. Тем самым ухудшается качество и стабильность обучения модели.

Нормализация

Простейший пример – нормализация в диапазон от 0 до 1:

function normalize(float $value, float $min, float $max): float {  
    $range = $max - $min;

    if ($range === 0.0) {
        return 0.0;
    }

    return ($value - $min) / $range;
}

Пример:

$features = [1.12, 0.85, 2.33, 4.67, 2.91, 0.44, 0.58, 0.76, 3.29, 0.50];

$min = min($features);
$max = max($features);
$result = [];

foreach ($features as $feature) {
    $normalizedFeature = normalize(value: $feature, min: $min, max: $max);
    $result[] = round($normalizedFeature, 2);
}

echo "Результат (normalized): \n";
echo print_r($result, true);

// Результат:
// Array (
//    [0] => 0.16
//    [1] => 0.1
//    [2] => 0.45
//    [3] => 1
//    [4] => 0.58
//    [5] => 0
//    [6] => 0.03
//    [7] => 0.08
//    [8] => 0.67
//    [9] => 0.01
// )

// Объяснение: (1.12 - 0.44) / (4.67 - 0.44) = 0.16

После такой обработки возраст, количество покупок и средний чек начинают "весить" примерно одинаково в пространстве признаков.

Стандартизация

Другой широко используемый подход – стандартизация признаков. В отличие от нормализации, она не ограничивает значения фиксированным диапазоном, а приводит распределение признака к виду с нулевым средним и единичным стандартным отклонением. Это особенно важно для моделей, которые чувствительны к масштабу признаков (линейная и логистическая регрессия, SVM, нейронные сети), а также для методов оптимизации, использующих градиентный спуск. Стандартизация делает признаки сопоставимыми по масштабу, но при этом сохраняет информацию о выбросах и относительных отклонениях значений.

Простейшая формула стандартизации выглядит так:

function standardize(float $value, float $mean, float $std): float {
    if ($std == 0.0) {
        return 0.0;
    }

    return ($value - $mean) / $std;
}

Пример:

// Допустим, это признак "время ответа пользователя" (в секундах)
$value = 8.5;
// Статистика по обучающей выборке
$mean = 5.0;   // среднее значение
$std  = 2.0;   // стандартное отклонение

$zScore = standardize($value, $mean, $std);

echo "Z-score для " . $value . " - " . round($zScore, 2) . "\n";

// Интерпретация
if ($zScore > 2) {
    echo "Значение сильно выше среднего (аномалия)";
} elseif ($zScore < -2) {
    echo "Значение сильно ниже среднего (аномалия)";
} elseif ($zScore > 1) {
    echo "Выше среднего";
} elseif ($zScore < -1) {
    echo "Ниже среднего";
} else {
    echo "В пределах нормы";
}

// Результат: 
// Z-score для 8.5 - 1.75
// Выше среднего

// Объяснение: (8.5 − 5.0) / 2.0 = 1.75

После стандартизации возраст, количество покупок и средний чек имеют среднее значение около нуля и сопоставимую дисперсию, благодаря чему обучение модели будет происходить стабильнее, а процесс оптимизации станет быстрее и предсказуемее.

Категориальные признаки и размерность

Не все признаки изначально числовые. Цвет, страна, тип устройства – все это категории. Чтобы поместить их в пространство признаков, их нужно превратить в числа. Чаще всего это делается через "one-hot encoding".

Если у нас есть три возможных цвета: red, green, blue, то один признак превращается в три координаты:

function encodeColor(string $color): array {
    return [
        $color === 'red' ? 1 : 0,
        $color === 'green' ? 1 : 0,
        $color === 'blue' ? 1 : 0,
    ];
}

echo 'Red: ' . encodeColor(color: 'red') . "\n";
echo 'Green: ' . encodeColor(color: 'green') . "\n";
echo 'Blue: ' . encodeColor(color: 'blue');

// Red:   [1, 0, 0]
// Green: [0, 1, 0]
// Blue:  [0, 0, 1]

Здесь важно заметить, что размерность имеет свойство резко расти. В нашем примере один логический признак превратился в три числовых. В настоящих задачах с сотнями категорий это становится серьезной проблемой и напрямую влияет на сложность моделей.

В реальных системах также приходится учитывать неизвестные или даже новые категории. Обычно для этого добавляют отдельный признак (например, "unknown"), который активируется, если значение не входит в обучающий словарь.

Почему данные – это точки в пространстве

Причина, по которой данные в машинном обучении рассматриваются как точки в пространстве, весьма проста. Большинство алгоритмов опираются на геометрию: расстояния, углы, проекции и поверхности.

Если у вас есть набор объектов, каждый из которых описан одним и тем же набором числовых признаков, то строгий математический способ работать с ними – рассматривать их как точки в одном и том же пространстве $R^n$ .

Формально: пусть каждый объект описывается вектором $x = (x ₁, x ₂, \dots, x ₙ)$ . Тогда вся выборка – это конечное множество точек ${x¹, x², …, xᵐ} ⊂ Rⁿ$ .

Расстояние между двумя точками $∣∣ x - y ∣∣$ отражает степень их сходства. Направление вектора $(x - y)$ показывает, в каких признаках объекты отличаются сильнее всего. Плоскость или гиперплоскость – это множество точек, удовлетворяющих линейному уравнению.

Именно поэтому даже самые разные модели в итоге сводятся к геометрическим операциям над векторами.

Геометрический смысл расстояний и углов

В пространстве признаков важны не только расстояния, но и углы между векторами.

Угол между векторами показывает, насколько два направления изменений похожи.

Интуитивно можно сказать так: нас интересует не столько абсолютная величина изменений, сколько то, в каких признаках они происходят одновременно. Даже если значения сильно различаются по масштабу, малый угол между векторами означает, что признаки изменяются согласованно.

Именно поэтому косинусное сходство часто используется при работе с текстовыми эмбеддингами и другими высокоразмерными данными, где направление вектора важнее его длины.

На практике такие векторы обычно предварительно нормализуют по длине (приводят к единичной норме), чтобы косинусное сходство отражало только направление векторов, а не их масштаб.

С формальной точки зрения всё это выражается через скалярное произведение. Скалярное произведение двух векторов $x\mathbf{x}$ и $y\mathbf{y}$ определяется как:

\mathbf{x} \cdot \mathbf{y} = \sum_{i=1}^{n} x_i y_i

Через него выражается косинус угла между векторами:

\cos(\theta) = \frac{\mathbf{x} \cdot \mathbf{y}}{|\mathbf{x}| |\mathbf{y}|}

Это напрямую используется, например, при сравнении текстовых эмбеддингов или пользовательских профилей.

С точки зрения машинного обучения это означает простую вещь: модель может считать два объекта похожими не потому, что они близки по всем координатам, а потому что они "смотрят" в одном направлении в пространстве признаков.

Связь с конкретными алгоритмами

Алгоритм k ближайших соседей (k-NN или k-Nearest Neighbors) буквально живет в пространстве признаков. Он ничего не обучает в классическом смысле, а просто для новой точки ищет k ближайших точек по выбранной метрике расстояния.

Другими словами, всё поведение этого алгоритма полностью определяется тем, как именно мы измеряем расстояния между точками.

Именно поэтому для алгоритма k-NN масштабирование признаков критично. Если признаки находятся в разных числовых диапазонах, расстояние между точками будет определяться в основном признаками с наибольшим масштабом, независимо от их реальной информативности.

Математически это выглядит так: для нового вектора x мы ищем такие векторы $x ᵢ$ из обучающей выборки, для которых расстояние $d (x, x ᵢ)$ минимально.

Функция указанная ниже реализует классическую формулу евклидова расстояния между двумя точками:

$\sqrt{\sum_{i=1}^{n} (a_i - b_i)^2}$

Евклидово расстояние – самый интуитивный и часто используемый способ измерять расстояние между точками в пространстве признаков, но оно не является универсальным. В зависимости от задачи и природы данных могут применяться другие метрики: например, манхэттенское расстояние или косинусная мера сходства. Разные метрики по-разному определяют понятие "близости" между объектами, и выбор метрики напрямую влияет на поведение алгоритма и результаты модели.

В следующей главе мы рассмотрим функцию вычисления евклидова расстояния подробней.

Однако не все модели опираются на расстояния между точками. Линейные модели смотрят на пространство иначе. Они ищут гиперплоскость, которая лучше всего разделяет точки или аппроксимирует их значения.

Формально линейная модель записывается так:

\mathbf{w} \cdot \mathbf{x} + b

Геометрически это означает, что все точки, для которых

\mathbf{w} \cdot \mathbf{x} + b = 0

лежат на одной гиперплоскости. Знак $f (x)$ определяет, по какую сторону границы находится точка.

Если подобрать более "инженерную" формулировку, то можно написать так:

Линейная модель разбивает пространство признаков гиперплоскостью, а знак линейной функции определяет класс объекта.

Функция ниже вычисляет:

\mathbf{w} \cdot \mathbf{x} + b = \sum_{i=1}^{n} w_i x_i + b

Геометрический смысл

Значение функции пропорционально расстоянию точки до разделяющей гиперплоскости.
Если $f (x) = 0$ – точка лежит на гиперплоскости.
Если $f (x) > 0$ или $f (x) < 0$ – по разные стороны границы.

function linearModel(array $x, array $w, float $b): float {
    $n = count($x);

    if ($n !== count($w)) {
        throw new InvalidArgumentException('Arguments x and w must have the same length');
    }

    $sum = $b;
    for ($i = 0; $i < $n; $i++) {
        $sum += $x[$i] * $w[$i];
    }

    return $sum;
}

Пример:

$x = [2, 3];        // входные признаки
$w = [0.5, 1.5];    // веса
$b = 1.0;           // смещение (bias)

$result = linearModel($x, $w, $b);
echo $result;

// Результат: 6.5
// Объяснение: b + (x[0] * w[0]) + (x[1] * w[1]) = 1.0 + (2 * 0.5) + (3 * 1.5) = 6.5

Нейронные сети – это следующий шаг усложнения. Каждый слой выполняет аффинное преобразование:

z = W x + b

А затем применяет нелинейную функцию активации. Геометрически это означает, что пространство сначала линейно поворачивается и растягивается, а затем нелинейно "ломается". После нескольких таких преобразований данные, которые были неразделимы линейно, становятся разделимыми.

Независимо от сложности архитектуры, вход у нейросети всегда один и тот же – вектор фиксированной размерности.

Высокая размерность и ее последствия

Когда размерность пространства признаков становится большой, возникают эффекты, которые на интуитивном уровне могут показаться странными. Объем пространства растет экспоненциально, точки становятся разреженными, а расстояния между ними выравниваются. Этот эффект часто называют "проклятием размерности".

Отсюда для разработчика напрашивается простой практический вывод: не добавляйте признаки "на всякий случай". Каждый признак должен иметь понятный смысл и пользу для задачи.

Связь с реальными моделями

Линейная регрессия, логистическая регрессия, нейронные сети – все они работают в пространстве признаков. Разница лишь в том, какие поверхности они могут в нем строить. Линейная модель проводит плоскость или гиперплоскость. Нейросеть – сложную нелинейную форму.

Но вход у них у всех один и тот же – вектор фиксированной размерности.

$features = [0.42, 0.15, 0.78, 0.03];
$prediction = $model->predict($features);

Если вы четко понимаете, что означает каждый элемент этого массива и в каком пространстве он находится, то половина проблем машинного обучения для вас уже решена.

Ключевая мысль

Векторы – это язык, на котором данные разговаривают с моделями. Размерность – это сложность этого языка. Пространство признаков – это сцена, на которой разворачивается все машинное обучение. Для разработчика важно перестать видеть в этом абстрактную математику и начать видеть хорошо структурированные массивы чисел, за которыми стоят реальные свойства реальных объектов.

Вся дальнейшая математика машинного обучения строится вокруг этой геометрической интерпретации: данные – это точки, модель – это поверхность, а обучение – процесс поиска формы, которая лучше всего разделяет или аппроксимирует эти точки.

Useful Resources

Адаптировано из книги «ИИ для PHP-разработчиков»:
https://apphp.gitbook.io/ai-for-php-developers
Онлайн-демо:
https://aiwithphp.org/books/ai-for-php-developers/examples/part-1/what-is-a-model

Vectors, Dimensions, and Feature Spaces — The Geometry Behind Machine Learning

Samuel Akopyan — Sun, 10 May 2026 20:36:47 +0000

If you strip machine learning of all the complex terminology and buzzwords, you almost always end up with the same core idea: we represent real-world objects as numbers and work with those numbers mathematically. This is where vectors, dimensions, and feature spaces come in. As PHP developers, it’s especially important to understand this intuitively rather than formally, because in code you’ll deal not with abstract linear algebra, but with arrays of numbers, matrices, and operations on them.

A vector as a way to describe an object

In machine learning, a vector is simply an ordered set of numbers. Each number represents some aspect of an object. If the object is simple, the vector is short. If the object is complex, the vector can be very long.

Imagine a user of an online store. We can describe them using: age, number of purchases per year, and average order value. Then one user is a vector of three numbers:

(age, purchases, average order value)

In PHP, this looks very straightforward:

$userVector = [35, 12, 78.5];

It’s important to understand: a vector is not just an array. The order of elements matters. If you swap age and average order value, the model won’t "figure out" what you meant. To it, these are completely different data.

Vector dimensionality

The dimensionality of a vector is the number of values it contains. In the example above, the dimensionality is 3. If you add another feature, say "days since last purchase", the dimensionality becomes 4.

Dimensionality is directly tied to how detailed your object description is. Low dimensionality means a rough description, high dimensionality means a more detailed one. But higher dimensionality is not always better. Every additional feature is both a new degree of freedom for the model and a potential source of noise.

It helps to think of dimensionality as a fixed contract. If a model expects a vector of length 10, you must always pass exactly 10 numbers, in the same order.

function predict(array $features): float {
    if (count($features) !== 10) {
        throw new InvalidArgumentException("Expected a vector of dimensionality 10");
    }

    // further computations
}

Example:

$features = [0.12, 0.85, 0.33, 0.67, 0.91, 0.44, 0.58, 0.76, 0.29, 0.50];

try {
    $result = predict($features);
    echo "Model score: " . round($result, 3) . "\n";

    // Interpret the result
    if ($result > 0.7) {
        echo "High probability of a positive outcome";
    } elseif ($result > 0.4) {
        echo "Medium probability";
    } else {
        echo "Low probability";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

// Model score: 0.75
// High probability of a positive outcome

Feature space

Formally, a feature space is usually denoted as $R^n$ . This means each object is represented by a vector $x = (x ₁, x ₂, \dots, x ₙ)$ of $n$ real numbers, and the set of all such vectors forms a single abstract space. Most machine learning models operate within this $n$ -dimensional space: vector addition and scalar multiplication are defined here, which allows us to use linear algebra tools. While formal axioms are rarely the focus in practice, it’s critical to understand that any model always operates within a fixed space defined by the structure of its input features.

If the dimensionality is 2, the feature space is a plane. If it’s 3, it’s the familiar 3D space. If it’s higher, we can no longer visualize it, but mathematically it’s still the same feature-engineering $R^n$ space.

Each point in this space is a real-world object translated into numbers. A user, a product, a document, an image – after preprocessing, all of them become points in feature space.

Feature space is the environment where the machine learning algorithm operates. Everything that used to be strings, dates, categories, and JSON becomes pure math – a set of numbers – after feature engineering.

Features as coordinate axes

Each feature is a separate coordinate axis in the space. Mathematically, this means the value $$xᵢ$$ is the coordinate of the point along the $i$ -th axis.

For example, the vector (35, 12, 78.5) is a point in 3D space where the first axis is age, the second is number of purchases, and the third is average order value.

This immediately explains a few important things.

First, features should be comparable in scale (another reason we convert everything to numbers). If one axis is measured in tens and another in hundreds of thousands, then distances and angles computed by the chosen metric stop reflecting true similarity between objects.

Second, adding a new feature means adding a new axis. The space becomes higher-dimensional (one more dimension), and each point gets an additional coordinate. The model now has to account for another direction when making decisions.

Normalization and scaling

In practice, you almost always need to bring features to comparable scales. This can be done in different ways: normalization (mapping values to a fixed range, for example from 0 to 1) or standardization (transforming the distribution to have zero mean and unit standard deviation). Both approaches solve the same engineering problem – making features comparable for the algorithm.

Depending on the data, logarithmic or other nonlinear transformations may also be used, but those are beyond the scope of this book.

It’s important to understand that normalization and scaling are not mathematical niceties, but practical necessities. Most machine learning algorithms are sensitive to the scale of input data: features with large numeric values start to dominate others, distorting the contribution of truly informative features. This reduces both the quality and stability of training.

Normalization

The simplest example is normalization to the range [0, 1]:

function normalize(float $value, float $min, float $max): float {  
    $range = $max - $min;

    if ($range === 0.0) {
        return 0.0;
    }

    return ($value - $min) / $range;
}

Example:

$result = normalize(value: 75, min: 50, max: 100);
echo $result; 

// Result: 0.5
// Explanation: (75 - 50) / (100 - 50) = 0.5

After this transformation, age, number of purchases, and average order value start to "weigh" roughly the same in feature space.

Standardization

Another widely used approach is feature standardization. Unlike normalization, it does not constrain values to a fixed range, but transforms the feature distribution to have zero mean and unit standard deviation. This is especially important for models that are sensitive to feature scale (linear and logistic regression, SVM, neural networks), as well as optimization methods based on gradient descent. Standardization makes features comparable while preserving information about outliers and relative deviations.

The basic standardization formula looks like this:

function standardize(float $value, float $mean, float $std): float {
    if ($std == 0.0) {
        return 0.0;
    }

    return ($value - $mean) / $std;
}

Example:

// Suppose this is the feature "user response time" (in seconds)
$value = 8.5;
// Statistics from the training dataset
$mean = 5.0;   // mean
$std  = 2.0;   // standard deviation

$zScore = standardize($value, $mean, $std);

echo "Z-score: " . round($zScore, 2) . "\n";

// Interpretation
if ($zScore > 2) {
    echo "Significantly above average (anomaly)";
} elseif ($zScore < -2) {
    echo "Significantly below average (anomaly)";
} elseif ($zScore > 1) {
    echo "Above average";
} elseif ($zScore < -1) {
    echo "Below average";
} else {
    echo "Within normal range";
}

// Result: 1.75
// Explanation: (8.5 − 5.0) / 2.0 = 1.75

After standardization, age, number of purchases, and average order value have a mean around zero and comparable variance, making training more stable and optimization faster and more predictable.

Categorical features and dimensionality

Not all features are numeric by default. Color, country, device type – these are categories. To place them in feature space, we need to convert them into numbers. The most common approach is one-hot encoding.

If we have three possible colors: red, green, blue, then one feature becomes three coordinates:

function encodeColor(string $color): array {
    return [
        $color === 'red' ? 1 : 0,
        $color === 'green' ? 1 : 0,
        $color === 'blue' ? 1 : 0,
    ];
}

echo 'Red: ' . encodeColor(color: 'red') . "\n";
echo 'Green: ' . encodeColor(color: 'green') . "\n";
echo 'Blue: ' . encodeColor(color: 'blue');

// Red:   [1, 0, 0]
// Green: [0, 1, 0]
// Blue:  [0, 0, 1]

Notice that dimensionality grows quickly. In this example, one logical feature turned into three numeric ones. In real-world tasks with hundreds of categories, this becomes a serious issue and directly affects model complexity.

In production systems, you also need to handle unknown or new categories. Typically, this is done by adding a separate feature (e.g., "unknown") that is activated when a value is not in the training vocabulary.

Why data is represented as points in space

The reason machine learning treats data as points in space is simple. Most algorithms rely on geometry: distances, angles, projections, and surfaces.

If you have a set of objects, each described by the same set of numeric features, the mathematically rigorous way to work with them is to treat them as points in the same space $R^n$ .

Formally: let each object be described by a vector $x = (x ₁, x ₂, \dots, x ₙ)$ . Then the dataset is a finite set of points ${x¹, x², …, xᵐ} ⊂ Rⁿ$ .

The distance between two points $∣∣ x - y ∣∣$ reflects how similar they are. The direction of the vector $(x - y)$ shows which features differ the most. A plane or hyperplane is the set of points satisfying a linear equation.

That’s why even very different models ultimately reduce to geometric operations on vectors.

Geometric meaning of distances and angles

In feature space, not only distances matter, but also angles between vectors.

The angle between vectors shows how similar two directions of change are.

Intuitively: we often care less about the absolute magnitude of change and more about which features change together. Even if values differ in scale, a small angle between vectors means the features change in a coordinated way.

That’s why cosine similarity is commonly used with text embeddings and other high-dimensional data, where direction matters more than magnitude.

In practice, such vectors are often normalized to unit length so that cosine similarity reflects only direction, not scale.

Formally, this is expressed via the dot product. The dot product of two vectors $x\mathbf{x}$ and $y\mathbf{y}$ is defined as:

\mathbf{x} \cdot \mathbf{y} = \sum_{i=1}^{n} x_i y_i

From this, the cosine of the angle between vectors is:

\cos(\theta) = \frac{\mathbf{x} \cdot \mathbf{y}}{|\mathbf{x}| |\mathbf{y}|}

This is directly used, for example, when comparing text embeddings or user profiles.

From a machine learning perspective, this means something simple: two objects can be considered similar not because they are close in all coordinates, but because they "point" in the same direction in feature space.

Connection to specific algorithms

The k-nearest neighbors algorithm (k-NN) literally lives in feature space. It doesn’t "learn" in the classical sense – it simply finds the k closest points to a new point using a chosen distance metric.

In other words, its entire behavior is determined by how we measure distance between points.

That’s why feature scaling is critical for k-NN. If features are on different scales, distances will be dominated by features with the largest values, regardless of their actual importance.

Mathematically, for a new vector $x\mathbf{x}$ , we look for vectors $x ᵢ$ from the training set such that the distance $d (x, x ᵢ)$ is minimal.

The function below implements the classic Euclidean distance between two points:

\sqrt{\sum_{i=1}^{n} (a_i - b_i)^2}

Euclidean distance is the most intuitive and commonly used way to measure distance in feature space, but it is not universal. Depending on the task and the nature of the data, other metrics may be used – for example, Manhattan distance or cosine similarity. Different metrics define "closeness" differently, and the choice of metric directly affects algorithm behavior and model results.

In the next chapter, we’ll look at the Euclidean distance function in more detail.

However, not all models rely on distances between points. Linear models view the space differently. They try to find a hyperplane that best separates points or approximates their values.

Formally, a linear model is written as:

\mathbf{w} \cdot \mathbf{x} + b

Geometrically, this means all points satisfying

\mathbf{w} \cdot \mathbf{x} + b = 0

lie on the same hyperplane. The sign of $$f(x)$$ determines which side of the boundary the point lies on.

A more "engineering-style" way to say this:

A linear model splits the feature space with a hyperplane, and the sign of the linear function determines the class of the object.

The function below computes:

\mathbf{w} \cdot \mathbf{x} + b = \sum_{i=1}^{n} w_i x_i + b

Geometric meaning:

The function value is proportional to the distance from the point to the separating hyperplane.
If $f (x) = 0$ – the point lies on the hyperplane.
If $f (x) > 0$ or $f (x) < 0$ – the point lies on different sides of the boundary.

function linearModel(array $x, array $w, float $b): float {
    $n = count($x);

    if ($n !== count($w)) {
        throw new InvalidArgumentException('Arguments x and w must have the same length');
    }

    $sum = $b;
    for ($i = 0; $i < $n; $i++) {
        $sum += $x[$i] * $w[$i];
    }

    return $sum;
}

Example:

$x = [2, 3];        // input features
$w = [0.5, 1.5];    // weights
$b = 1.0;           // bias

$result = linearModel($x, $w, $b);
echo $result;

// Result: 6.5
// Explanation: b + (x[0] * w[0]) + (x[1] * w[1]) = 1.0 + (2 * 0.5) + (3 * 1.5) = 6.5

Neural networks are the next level of complexity. Each layer performs an affine transformation:

z = W x + b

Then applies a nonlinear activation function. Geometrically, this means the space is first linearly rotated and stretched, and then nonlinearly "bent". After several such transformations, data that was not linearly separable becomes separable.

Regardless of architectural complexity, the input to a neural network is always the same – a vector of fixed dimensionality.

High dimensionality and its consequences

When the dimensionality of feature space becomes large, effects appear that may seem counterintuitive. The volume of space grows exponentially, points become sparse, and distances between them start to even out. This is often called the "curse of dimensionality".

From a developer’s perspective, the practical takeaway is simple: don’t add features "just in case". Every feature should have a clear meaning and value for the task.

Connection to real models

Linear regression, logistic regression, neural networks – they all operate in feature space. The difference is in what kind of surfaces they can construct. A linear model builds a plane or hyperplane. A neural network builds a complex nonlinear surface.

But the input is always the same – a vector of fixed dimensionality.

$features = [0.42, 0.15, 0.78, 0.03];
$prediction = $model->predict($features);

If you clearly understand what each element of this array represents and in which space it lives, you’ve already solved half of the problems in machine learning.

Key idea

Vectors are the language data uses to talk to models. Dimensionality is the complexity of that language. Feature space is the stage where all machine learning happens. As a developer, it’s important to stop seeing this as abstract math and start seeing well-structured arrays of numbers that represent real properties of real objects.

All further machine learning math builds on this geometric interpretation: data are points, the model is a surface, and training is the process of finding the shape that best separates or approximates those points.

Useful Resources

Originally adapted from the book "AI for PHP Developers":
https://apphp.gitbook.io/ai-for-php-developers
Online Demo:
https://aiwithphp.org/books/ai-for-php-developers/examples/part-1/what-is-a-model

Logistic Regression on MNIST (0 vs 1) in PHP: A Simple Example

Samuel Akopyan — Sat, 11 Apr 2026 16:47:38 +0000

Want to get a real feel for machine learning in practice?

Here’s a simple but powerful exercise: classify thousands of digits (0 vs 1) from the MNIST dataset (12,666 train samples and 2,116 test samples) using logistic regression — trained with gradient descent. Just 5 epochs.

What you’ll get out of it:

see how a model actually works with image data
understand where linear models start to break down
try a clean implementation in pure PHP: accuracy: 99.91%
compare it with a more production-ready approach using RubixML: accuracy: 99.95%

If you’ve been meaning to move from theory to something hands-on, this is a great place to start:
https://aiwithphp.org/books/ai-for-php-developers/examples/part-3/logistic-regression/case-0/mnist-0-1

From Arrays to GPU - how the PHP ecosystem is moving toward real ML

Samuel Akopyan — Mon, 06 Apr 2026 20:13:25 +0000

From Arrays to GPU - how the PHP ecosystem is moving toward real ML
Why PHP arrays are a poor fit for math, how Tensor and NDArray emerged, and why RubixML eventually moved toward GPU.

Whenever I talk to someone or write about "machine learning in PHP", the reaction is usually predictable: people either smirk, point to Python, or downvote (except for those who are genuinely interested).

The general conclusion is simple - this is just not what the language is for.

And honestly, there is some truth in that. But…

For several years now, I've been trying to push the idea of "ML in PHP". Why? I'm not entirely sure. I've asked myself that question many times and still don't have a clear answer - even for myself.

I'm not crazy, and I'm not obsessed with some fixed idea.

I'm just a regular developer who enjoys writing PHP.
This language has paid my bills for years (and still does). It's not perfect, but overall I like how it evolves and where it's heading.

So it feels like the very idea of "ML in PHP" is a kind of challenge that keeps me up at night - trying to understand math formulas or implement yet another ML algorithm in PHP. And honestly - I enjoy it.

Of course, PHP was never designed for numerical computing. It has no built-in support for vector operations, no real control over memory, and no access to low-level optimizations that are standard in scientific computing.

And yet - machine learning in PHP exists.

Not as an experiment, but as part of real systems:

inference directly inside web applications
data processing inside SaaS
automation and embedded analytics

And every month - the use of ML in PHP keeps growing.

If you're skeptical, take a look here:
👉 https://github.com/apphp/awesome-php-ml

This is one of the most complete curated lists of machine learning, AI, NLP, LLM, and data analysis libraries for PHP - over 140 resources. The PHP ML ecosystem is not loud, but it's fairly mature. It consists of four layers:

classical ML libraries
mathematical foundation
integration tools with modern ML systems
integration with external ML services

In this article, we'll focus on the first two layers, and only briefly touch the other two.

Despite the ecosystem being alive and growing, if you look deeper, it becomes clear: it evolved not thanks to the language, but despite its limitations - driven by a handful of enthusiasts (I'll try to mention as many as I know).

Let me repeat a cliché - this article is not a library overview and not a comparison of PHP vs Python.

It's a story of how the PHP community gradually arrived at the same conclusion:

the problem is not the algorithms - it's the runtime model itself.

At first, vectors and matrices were implemented as plain PHP arrays. Then came optimization attempts. Then native structures written in C and Rust. And at some point it became obvious: even that is not enough.

The next step was inevitable - moving computation to the GPU.

We'll walk through this path step by step: from naive implementations to modern solutions like Tensor, NDArray, and GPU backends in RubixML.

Along the way, we'll see how not only the API changed, but also the understanding of where PHP ends - and where a real computational system or orchestration layer begins.

In short: this is not a story about how to do ML in PHP, but why it had to be done differently.

2. First attempt: when a matrix is just an array

If we ignore theory, a matrix is just a table of numbers. And since PHP already has arrays, you can represent a matrix as an array of arrays:

$matrix = [
    [1.0, 2.0, 3.0],
    [4.0, 5.0, 6.0],
];

This idea was the foundation of the first ML libraries in PHP:

PHP-ML - https://github.com/jorgecasas/php-ml (by Arkadiusz Kondas)
early versions of RubixML - https://github.com/RubixML/RubixML (by Andrew DalPino)
and a few others

Everything was written in pure PHP - no extensions, no native code (meaning all computations were done by the interpreter, without low-level optimizations).

From a developer's perspective, this was extremely convenient: no compilation required, easy debugging with familiar tools, and fully transparent code.

What it looked like in code

Even operations like matrix multiplication were implemented very directly - using three nested loops:

function matmul(array $a, array $b): array {
    $result = [];

    $rowsA = count($a);
    $colsA = count($a[0]);
    $colsB = count($b[0]);

    for ($i = 0; $i < $rowsA; $i++) {
        for ($j = 0; $j < $colsB; $j++) {
            $sum = 0.0;
            for ($k = 0; $k < $colsA; $k++) {
                $sum += $a[$i][$k] * $b[$k][$j];
            }
            $result[$i][$j] = $sum;
        }
    }

    return $result;
}

Or, for example, a dot product:

function dot(array $a, array $b): float {
    $sum = 0.0;

    for ($i = 0, $n = count($a); $i < $n; $i++) {
        $sum += $a[$i] * $b[$i];
    }

    return $sum;
}

From an algorithmic point of view - everything is correct.
From a PHP point of view - everything is "by the book".

For a human - it's clear and readable. And most importantly, it works.

In fact, this approach never really disappeared.

Even today, you can find fresh examples where neural networks are implemented in pure PHP - without external libraries or extensions. Usually not for production, but for learning: to understand how things work "under the hood" and how complex algorithms are built from simple operations.

For example (manual forward pass of a neural network layer):
function forward(array $inputs, array $weights, array $biases):

array {
    $outputs = [];

    foreach ($weights as $i => $neuronWeights) {
        $sum = 0.0;

        foreach ($neuronWeights as $j => $weight) {
            $sum += $inputs[$j] * $weight;
        }

        $sum += $biases[$i];
        $outputs[$i] = 1 / (1 + exp(-$sum));
    }
    return $outputs;
}

This is an important point.

On one hand, it shows that:

the approach is still understandable
it's still useful for learning and experimentation

On the other hand - its limitations become obvious very quickly when you try to scale or move to production.

If you're interested in looking ahead, I recommend watching Alexey Nechaev's relatively recent talk (It's in Russian, but I promise you'll have a blast watching it):

It walks you through the implementation of a neural network step by step, directly in PHP, using the same concepts: arrays, loops, and basic mathematical operations.

Why it was convenient

The main advantage - simplicity.

If you're motivated, you can implement in one evening:

k-NN
simple linear regression
a basic classifier
etc.

All without leaving PHP.

For example, a piece of logistic regression:

function sigmoid(float $x): float {
    return 1 / (1 + exp(-$x));
}

function predict(array $weights, array $features): float {
    return sigmoid(dot($weights, $features));
}

As I like to say - "everything is neat and old-school".

On small datasets, this works fine.
For learning, experiments, and prototypes - more than enough.

Problems start a bit later.

3. Why it stops working

The problems don't appear immediately.

At first everything looks fine. Then the data grows - and the code starts slowing down. First a little, then dramatically, and eventually it becomes unusable.

The first instinct is: "we need to optimize the loops". But very quickly it becomes clear - the issue is not the algorithms or the code itself. Loop optimizations don't help much.

The problem is deeper - in how PHP works internally.

A number is not just a number

In PHP, a number is not a primitive - it's a zval structure that stores:

type
value
metadata (e.g., reference count)

So instead of compact 4–8 bytes like in C, each element takes much more memory.

If you have a million elements - that's a million such structures.

An array is a hash table

A PHP array is not contiguous memory - it's typically a hash table (except for packed arrays).

That means elements are not stored next to each other. Access is not just "index lookup", but a sequence of operations:

key lookup
traversal of internal structures
extraction of the zval

For example:

$value = $matrix[10][5];

Under the hood, this is a series of operations, not a direct memory access.

This immediately impacts several things:

CPU cache efficiency drops
data access becomes more expensive
no automatic SIMD vectorization at the PHP level

In numerical computing, this is critical.

Copy-on-write

There is another less obvious issue - copy-on-write.

PHP may implicitly copy arrays when modified:

$b = $a;
$b[0][0] = 42;

You don't always control when the copy happens.

In matrix-heavy workloads, this can:

significantly increase memory usage
introduce extra allocations

No vectorization

All operations are done via loops:

for (...) {
    $c[$i] = $a[$i] + $b[$i];
}

Whereas in NumPy this is a single operation executed in C using SIMD (Single Instruction, Multiple Data).

So you end up in a strange situation: the algorithm is correct, the code is simple - but every operation is too expensive.

And that's why everything suddenly breaks when data grows.

What it looks like in practice

Let's compare a simple operation - matrix multiplication.

Option 1: pure PHP

function matmul(array $a, array $b): array {
    $result = [];

    $rowsA = count($a);
    $colsA = count($a[0]);
    $colsB = count($b[0]);

    for ($i = 0; $i < $rowsA; $i++) {
        for ($j = 0; $j < $colsB; $j++) {
            $sum = 0.0;
            for ($k = 0; $k < $colsA; $k++) {
                $sum += $a[$i][$k] * $b[$k][$j];
            }
            $result[$i][$j] = $sum;
        }
    }

    return $result;
}

Option 2: Tensor

(https://github.com/RubixML/Tensor)

use Tensor\Matrix;

$a = Matrix::rand(500, 500);
$b = Matrix::rand(500, 500);

$c = $a->matmul($b);

Option 3: NumPower (potential GPU)

(https://github.com/RubixML/numpower)

$c = NumPower::multiply($a, $b);
// or
$c = $a * $b;

Results (approximate)

Approach Time for matrix 500x500

PHP arrays ~ 10–20 sec
Tensor (CPU) ~ 0.3–0.8 sec
GPU (NumPower) ~ 0.05–0.2 sec

The exact numbers depend on hardware, but the order of magnitude remains.

The key point is not absolute values - it's the orders of magnitude difference.

And this is where it becomes clear: the issue is not that PHP is "slow" or "bad" - it's that it's using the wrong tool for the job.

4. Optimization attempts - and why they don't save it

For example, you can remove repeated count() calls and reduce array access:

$count = count($a);

for ($i = 0; $i < $count; $i++) {
    $ai = $a[$i];
    $bi = $b[$i];
    $sum += $ai * $bi;
}

This:

calls count() once instead of every iteration
reduces array access
uses local variables, which are faster

It does give a small speedup, especially in large loops. But the gain is modest and depends heavily on the code and PHP version.

You quickly hit the limits of such micro-optimizations.

The core issue is that this is optimization at the syntax level.

The fundamental limitations remain:

no memory control
no contiguous storage
no SIMD
no BLAS

The bottleneck is not the loop - it's PHP's memory model.

Still, optimizations didn't stop there.

Optimization: transposition

A common trick is to transpose the second matrix in advance.

The issue with naive multiplication in PHP is frequent column access:

$sum += $a[$i][$k] * $b[$k][$j];

Accessing $a[$i][$k] is fine – it's row-wise.
But $b[$k][$j] is column access – inefficient in PHP arrays.

As a result, we are constantly jumping around in memory.

👉 For a fun way to pass the time, I highly recommend watching the video of Andrew DalPino (author of the RubixML library):

The solution here is deadly simple: transpose the second matrix in advance:

function transpose(array $matrix): array {
    $result = [];

    foreach ($matrix as $i => $row) {
        foreach ($row as $j => $value) {
            $result[$j][$i] = $value;
        }
    }
    return $result;
}

Then:

function matmulOptimized(array $a, array $b): array {
    $bT = transpose($b);
    $result = [];

    $rowsA = count($a);
    $colsB = count($bT);
    for ($i = 0; $i < $rowsA; $i++) {
        for ($j = 0; $j < $colsB; $j++) {
            $sum = 0.0;
            for ($k = 0; $k < count($a[0]); $k++) {
                $sum += $a[$i][$k] * $bT[$j][$k];
            }
            $result[$i][$j] = $sum;
        }
    }
    return $result;
}

Now we always work with rows:

$bT[$j][$k] // instead of $b[$k][$j]

Why it helps:

fewer memory "jumps"
better CPU cache usage
more predictable access

This can noticeably improve performance even in pure PHP.

But - there's a catch.

We still:

use zval
use hash tables
run inside the interpreter

So we're making things less bad - but not truly efficient.

At some point, you have to admit: even advanced PHP tricks won't replace a proper data model.

PHP was not designed for high-performance numerical computing.

Optimization: CPU cache

Another idea - improve cache locality.

In low-level languages (C, C++, NumPy), performance heavily depends on how data is laid out in memory.

If data is contiguous, the CPU can read it in blocks (cache lines):

for ($i = 0; $i < $n; $i++) {
    $sum += $a[$i] * $b[$i];
}

This is fast in C not because it's simple, but because:

data is contiguous
CPU reads it in blocks
access is predictable

So naturally, you try:

row-based access
minimize randomness
use linear structures

Where it breaks in PHP

Even with a "flat" array:

$a = [1.0, 2.0, 3.0, 4.0];

In memory this is:

not a sequence of floats
but an array of zval
still backed by internal structures

So:

data is not compact
there is overhead between elements
CPU cache is not used efficiently

You end up optimizing as if cache matters - but getting little benefit.

Optimization: packed arrays

PHP 7+ introduced packed arrays for simple cases:

$a = [1, 2, 3, 4, 5];

These are more compact and faster.

But for matrices:

$matrix = [
    [1, 2, 3],
    [4, 5, 6],
];

You still get an array of arrays - not truly contiguous.

And:

each element is still a zval
no real contiguous memory

Plus, packed arrays are fragile:

$a = [1, 2, 3];
$a[10] = 4; // breaks packing

In ML workloads (filtering, reshaping, indexing), this happens all the time.

If you combine everything - transposition, cache tricks, packed arrays - you see the same pattern:

we can speed things up a bit - but we can't change the foundation.

And again we arrive at the key insight:

the problem is not how we write loops –
the problem is how data is represented in memory.

A subtle but important point

There's another aspect that's rarely discussed.

Many libraries from that era simply stopped evolving. The internet is full of abandoned PHP ML pet projects.

Not because the idea was bad - quite the opposite. It was logical.

But developers quickly hit the same ceiling.

They could:

rewrite internals
add more optimizations
improve APIs

But it didn't lead to fundamental gains.

At some point, authors realized:

no matter how much you optimize PHP arrays, they won't become suitable for numerical computing.

And then there were only two options:

rewrite everything in C / Rust
lose motivation

Often, it was the second.

Enthusiasm fades when each step brings diminishing returns, while the core problem remains.

And this is one of the clearest signals:

the issue was not in the libraries –
it was in the model itself.

5. The turning point: when matrices stop being arrays

The next stage was simple - stop treating matrices as PHP arrays.

Libraries and extensions appeared that store data outside PHP structures.

For example:

Rubix Tensor (from the already known to us Andrew DalPino) - https://github.com/RubixML/Tensor
NDArray (implementation using Rust by Kyrian Obikwelu) - https://github.com/phpmlkit/ndarray

Now data is stored in contiguous memory, like in NumPy. This is a completely different level.

The code looks similar:

use Tensor\Matrix;

$a = Matrix::quick([
    [1, 2],
    [3, 4],
]);
$b = Matrix::quick([
    [5, 6],
    [7, 8],
]);
$c = $a->matmul($b);

But internally everything changes:

no zval per element
no hash table
tightly packed data
efficient CPU usage

Rust plays an interesting role here. In NDArray, it provides performance without typical C memory pitfalls. It's a good example of PHP delegating heavy work to other languages.

And it works - speedups can be significant.

But even this is not the end.

Architecture shift

Simplified evolution:
PHP arrays
    ↓
(realization of limitations)
    ↓
Native structures (Tensor, ndarray)
    ↓
C / Rust extensions

More broadly - this is a shift in roles:

before: PHP did computations
now: PHP orchestrates

And interestingly, code becomes not just faster - but less "PHP-like" and closer to actual math.

Higher-level operations

$c = $a->add($b);
$c = $a->divide($a->sum());

This reads almost like formulas.

But something still feels missing.

The API is still object-oriented, not fully mathematical.

NumPower and a new abstraction level

NumPower (originally created by Henrique Borba, not it's a part of RubixML) goes further:

$c = NumPower::multiply($a, $b);
// or
$c = $a * $b;

Even:

$y = $a / $b;

This is not just syntax sugar - it's making math expressions native to the language.

6. A new ceiling: when CPU is not enough

As workloads grow, it becomes clear - the problem is not just PHP.
Even with perfect data structures and fast native code, CPU has limits: cores and bandwidth.

ML tasks are essentially massive matrix operations.

At some scale, even optimized CPU implementations struggle.

So we move to the next logical step.

7. Why everything leads to GPU

GPU is built for parallel computation: thousands of threads, high memory bandwidth - perfect for linear algebra.

Today it's obvious: squeezing more out of CPU is a dead end for many ML workloads.

You need to change the architecture.

What's happening now

RubixML v3 is moving toward GPU via projects like NumPower:

👉 https://github.com/RubixML/numpower

This is a paradigm shift:

PHP → orchestration
Tensor / NumPower → computation
GPU → heavy math

**This is still driven by enthusiasts and under active development.

If you're interested - this is a great time to get involved:**

👉 https://github.com/RubixML/ML/tree/3.0

This is no longer about "optimizing computation". It's about changing the model: PHP becomes an orchestrator, delegating heavy work to native layers.

8. What actually happened

Looking at the evolution, the picture is quite logical.

First, PHP was used as a compute environment. Then it became clear it's not suited for that. Then computation moved outward: first to native structures, then extensions, and now GPU.

Today, PHP in ML is mostly an orchestration layer. It connects components, manages processes, handles data - while heavy math happens elsewhere:

GPU
Rust
native libraries

And that's probably the key takeaway.

A practical example

We have projects like:

👉 https://github.com/CodeWithKyrian/transformers-php (by Kyrian Obikwelu)

This library gives access to modern models (like Hugging Face transformers) in PHP.

But under the hood, PHP is not doing heavy computation.

It:

manages the pipeline
loads models
processes results

Computation happens outside PHP - via native libraries or external runtimes.

Example:

use function Codewithkyrian\Transformers\Pipelines\pipeline;

// Allocate a pipeline for sentiment analysis
$classifier = pipeline('sentiment-analysis');

$out = $classifier(['I love transformers!']);
echo print_r($out, true) . PHP_EOL;

$out = $classifier(['I hate transformers!']);
echo print_r($out, true);

This shows how PHP's role changed:

before:

// we implement the mathematics ourselves
$sum += $inputs[$i] * $weights[$i];

now:

// we use a ready-made ML infrastructure
$result = $pipeline($text);

Similarly, libraries like:

👉 https://github.com/llphant/llphant (by Franco Lombardo, Fabrizio Balliano and others)

LLPhant moves even higher - working with full LLM scenarios:

text generation
embeddings
retrieval (RAG)
chat interfaces

Example:

use LLPhant\Chat\Enums\ChatRole;
use LLPhant\Chat\Message;
use LLPhant\Chat\OpenAIChat;
use LLPhant\OpenAIConfig;

$chat = new OpenAIChat(new OpenAIConfig(...));

$message = new Message();
$message->role = ChatRole::User;
$message->content = 'What is the capital of France? ';

$response = $chat->generateText((string)$message);
echo $response;

Embeddings:

use LLPhant\Embeddings\OpenAI\EmbeddingGenerator;

$generator = new EmbeddingGenerator();

$embedding = $generator->embed("PHP and machine learning");

php

Now we no longer think about:

matrices
loops
memory

We think about:

data
requests
system behavior

And the transformation doesn't stop here.

Higher-level tools are emerging where PHP is not just a wrapper, but an environment for building AI logic.

For example:

👉 https://github.com/neuron-core/neuron-ai (by Valerio Barbera)

Neuron AI focuses on:

agents
chains
LLM integrations

Example:

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo "Q1: Hi!\n";
echo "A: " . $message->getContent() . "\n\n";
echo "Q2: Explain who you are?\n";
echo "A: ". MyAgent::make()
    ->chat(new UserMessage("Explain who you are?"))
    ->getMessage()
    ->getContent();

Here it's especially clear how PHP's role evolved:

before - we implemented math
then - we moved it to native structures
now - we describe system behavior

9. Conclusion

Looking at the full journey over the last ten years, it becomes clear: this is not just an evolution of tools - it's a gradual displacement of PHP from computation.

First, we honestly multiply matrices in arrays.
Then we optimize and hit a ceiling.
Then we move to native structures.
Then to C / Rust.
And eventually… to GPU.

PHP arrays
    ↓
(realization of limitations)
    ↓
Native structures (Tensor, ndarray)
    ↓
C / Rust extensions
    ↓
GPU (NumPower, RubixML v3)

And here's a somewhat uncomfortable conclusion:

PHP is not becoming faster at ML.
It's just stopping doing the math.

It's no longer a compute engine - it's a dispatcher, an orchestrator, glue between components.

And maybe that's exactly its chance to stay relevant.

But the question remains:

*Is the game still going on?
Or has PHP been playing a different game for a while now?
*

If you're interested in the topic, you can dive deeper in my free book:
https://apphp.gitbook.io/ai-for-php-developers/

And explore interactive examples:
https://aiwithphp.org/books/ai-for-php-developers/examples/

What a ML Model Really Is (From a Mathematical Perspective)

Samuel Akopyan — Sat, 21 Mar 2026 12:23:00 +0000

When we talk about a model in machine learning, it helps to immediately drop all associations with “artificial intelligence” and complex abstractions.

At its core, a model is simply a function.

Nothing more, nothing less.

It takes some input data and returns a result. The only difference is that this function isn’t fixed — it has parameters that can be adjusted.

If you’re a PHP developer, this should feel very familiar. A model is essentially just a function or class method:

it takes inputs
performs some computation
returns a value

A Model as a Function

In its most general form, a model looks like this:

f(x) = ŷ

x — input data
ŷ — predicted output

The “hat” on ŷ is intentional: it’s not the true value, just an estimate.

Function as the Foundation of a Model

Let’s make it concrete.

Suppose we want to predict the price of an apartment based on its size. A simple linear model would look like this:

ŷ = w * x + b

This already is a complete model.

It says:

“The predicted price is the area multiplied by some coefficient, plus an offset.”

Now let’s translate that into PHP:

class LinearModel {
    private float $w;
    private float $b;

    public function __construct(float $w, float $b) {
        $this->w = $w;
        $this->b = $b;
    }

    public function predict(float $x): float {
        return $this->w * $x + $this->b;
    }
}

Example usage:

$model = new LinearModel(2.0, 0.0);
echo $model->predict(3.0);

// Result: 6
// Explanation: 2 * 3 + 0 = 6

From a PHP perspective, this is just a regular class.

From a machine learning perspective — this is a model.

Model Parameters

The key idea here is parameters.

In our example:

w — weight
b — bias

These are not inputs. They define how the model behaves.

Change them → you change the output.

It’s important to distinguish between:

Input (x) — comes from outside
Parameters (w, b) — live inside the model
Output (ŷ) — the prediction

In traditional programming, you hardcode parameters.

In machine learning, it’s the opposite:

The structure is fixed, but the parameters are learned automatically.

Error as a Measure of Quality

Now the key question:

How do we know if one set of parameters is better than another?

We introduce error (also called a loss function).

This is just another function that measures how wrong the model is.

A simple version:

ŷ - y

PHP version:

function error(float $yTrue, float $yPredicted): float {
    return $yPredicted - $yTrue;
}

Example:

echo error(yTrue: 10.0, yPredicted: 7.0);

// Result: -3
// Explanation: 7 - 10 = -3

In practice, we usually use squared error:

(ŷ - y)^2

function squaredError(float $yTrue, float $yPredicted): float {
    return ($yPredicted - $yTrue) ** 2;
}

Example:

echo squaredError(yTrue: 4.0, yPredicted: 6.0);

// Result: 4
// Explanation: (6 - 4)^2 = 4

Important detail:

Error depends on ŷ, which depends on model parameters.

So ultimately:
error is a function of the parameters.

Training = Minimizing Error

Now everything comes together.

We have:

a model (function with parameters)
data (inputs + correct outputs)
error (how wrong the prediction is)

Training is simply:

Finding parameter values that minimize error.

Even in PHP, you can imagine it like this:

$dataset = [
    [1.0, 2.0],
    [2.0, 4.0],
];

$model = new LinearModel(w: 0.0, b: 0.0);

foreach ($dataset as [$x, $yTrue]) {
    $yPredicted = $model->predict($x);
    $loss = squaredError($yTrue, $yPredicted);

    // In real ML, parameters would be updated here
}

Initial (bad) model:

$model = new LinearModel(w: 0.0, b: 0.0);
// y = 0 * x

// x = 1 → loss = 4
// x = 2 → loss = 16

After some improvement:

$model = new LinearModel(w: 0.8, b: 0.0);
// y = 0.8 * x

// x = 1 → loss = 1.44
// x = 2 → loss = 5.76

And so on — parameters are adjusted to reduce the loss.

The exact update method (gradient descent, etc.) is a separate topic.

But the core idea is simple:

We don’t tell the model the rules.
We tell it how wrong it is — and it improves.

Why This Matters

For a PHP developer, this perspective is crucial.

Machine learning does not replace programming.

It builds on the same foundations:

functions
parameters
computations

Let’s strip away the hype:

A model is just a function
Training is just optimization
Error is just another function

Once you see it this way, machine learning stops being mysterious.

It becomes engineering:

choosing the right function
defining the right loss
efficiently finding good parameters

Try It Yourself

You can run the code examples here:

👉 https://aiwithphp.org/books/ai-for-php-developers/examples/part-1/what-is-a-model

Что такое ML модель в математическом смысле

Samuel Akopyan — Sat, 21 Mar 2026 11:56:02 +0000

Как это выглядит для PHP-разработчика
Проще всего понять это через привычную аналогию.
Любая модель очень похожа на обычную функцию или метод:
есть входные аргументы
есть вычисления
есть возвращаемое значение

В самом общем виде модель записывается так: f(x) = ŷ, где
x - входные данные
ŷ - предсказание модели

Важно: это не истинное значение, а лишь попытка его угадать.

Функция как основа модели
Допустим, мы хотим предсказывать цену квартиры по её площади.
Самая простая модель - линейная: ŷ = w · x + b
Она говорит:
Цена ≈ площадь × коэффициент + сдвиг

PHP-реализация
class LinearModel {
    private float $w;
    private float $b;

    public function __construct(float $w, float $b) {
        $this->w = $w;
        $this->b = $b;
    }

    public function predict(float $x): float {
        return $this->w * $x + $this->b;
    }
}

Пример:

$model = new LinearModel(2.0, 0.0);
echo $model->predict(3.0);

// Результат: 6
// Объяснение: 2 * 3 + 0 = 6

С точки зрения PHP - это обычный класс.
С точки зрения машинного обучения - это уже модель.

Параметры модели
Ключевой момент - параметры.
В нашем случае это: w и b
Они не являются входными данными, но именно от них зависит поведение модели.
Важно чётко разделять:
входные данные (x) - приходят извне
параметры (w, b) - настраиваются
выход (ŷ) - результат

В классическом программировании параметры фиксированы.
В машинном обучении - наоборот: структура фиксирована, параметры подбираются автоматически.

Ошибка как мера качества
Как понять, хороша ли модель?
Для этого используется функция ошибки (loss function).
Она сравнивает:
предсказание (ŷ)
реальное значение (y)

и возвращает число - насколько модель ошиблась.

Простая ошибка
Например, самая простая функция потерь - разница между предсказанием и реальным значением: ŷ - y

function error(float $yTrue, float $yPredicted): float {
    return $yPredicted - $yTrue;
}

Пример:

echo error(yTrue: 10.0, yPredicted: 7.0);
// Результат: -3
// Объяснение: 7 - 10 = -3

Квадрат ошибки (чаще используется)
На практике чаще используют квадрат ошибки (Squared Error или SE), потому что он всегда положительный и сильнее наказывает большие промахи: (ŷ - y)²

function squaredError(float $yTrue, float $yPredicted): float {
    return ($yPredicted - $yTrue) ** 2;
}

Пример:

echo squaredError(yTrue: 4.0, yPredicted: 6.0);

// Результат: 4
// Объяснение: (6 - 4)^2 = 4

Почему именно квадрат:

всегда положительный
сильнее наказывает большие ошибки

Важное наблюдение
Ошибка зависит от ŷ.
А ŷ зависит от параметров (w, b).
👉 Значит, ошибка - это функция параметров модели.

Обучение как минимизация ошибки
Если собрать всё вместе:

модель - функция с параметрами
данные - пары (x, y)
ошибка - мера качества

👉 Обучение = подбор параметров, уменьшающих ошибку

Простейшая иллюстрация на PHP

$dataset = [
    [1.0, 2.0],
    [2.0, 4.0],
];

$model = new LinearModel(w: 0.0, b: 0.0);

foreach ($dataset as [$x, $yTrue]) {
    $yPredicted = $model->predict($x);
    $loss = squaredError($yTrue, $yPredicted);

    // здесь параметры должны обновляться,
    // чтобы уменьшить loss
}

До обучения

$model = new LinearModel(w: 0.0, b: 0.0);

// Результат:
// y = 0 * x
// x = 1 → loss = 4
// x = 2 → loss = 16

После частичного обучения

$model = new LinearModel(w: 0.8, b: 0.0);

// Результат:
// y = 0.8 * x
// x = 1 → loss = 1.44
// x = 2 → loss = 5.76

Параметры постепенно меняются так, чтобы ошибка уменьшалась.

Ключевая идея
Никто не «объясняет» модели правила.
Мы просто:

даём данные
считаем ошибку
уменьшаем её

Почему это важно для PHP-разработчика
Это понимание убирает магию.
Модель - это функция
Обучение - это оптимизация
Ошибка - обычная функция

Машинное обучение не противоречит программированию - оно продолжает его.

Что дальше
Когда это становится понятно, начинается настоящая инженерия:
какие функции использовать
какие ошибки выбирать
как оптимизировать параметры

Полезные материалы
Книга: https://apphp.gitbook.io/ai-for-php-developers
Онлайн-демо: https://aiwithphp.org/books/ai-for-php-developers/examples/part-1/what-is-a-model

AI for PHP Developers. Practical Use of TransformersPHP

Samuel Akopyan — Mon, 09 Feb 2026 21:22:28 +0000

AI in PHP: Not Theory, but a Real Starting Point

In my previous articles, I described at a fairly high level why AI seems to be everywhere, yet barely intersects with everyday PHP development. Not because PHP is "unsuitable", but because the conversation usually happens outside our tasks and our habitual way of thinking. And, of course, because there is very little material that explains AI specifically for PHP developers - their problems and their mindset.

After the publication, I was asked the same question several times, in different forms:

Okay, suppose that's true. Where do you actually start?

And this is probably the most interesting question I received. Below, I'll try to answer it.

About the "Entry Point"

When you hear "using AI in a project", your mind likely jumps to a lot of unnecessary things at once: infrastructure, model training, experiments, separate services, new roles in the team, and so on.

But honestly, in most PHP projects we simply don't need all that (even though figuring it out is a fascinating task in itself).

In practice, we do not need to:

train models from scratch
understand gradient descent
collect datasets, etc.

It's important to understand that AI ≠ Data Science. My friends, in most PHP projects no one trains models. Please remember this! At least when we're talking about applied PHP projects that use ready-made models, not research or model training.

What we actually need is to take an existing tool and carefully integrate it into the current logic of the application - just like we do with any other library.

And this is where things get interesting.

What Is TransformersPHP, and What Do You Do With It?

Everyone already knows about using LLMs via APIs. It's useful and convenient, but in that form AI remains something external - a service you send text to. What's inside is a black box.

At some point, I wanted to look at a more "down-to-earth" level: not text generation, but semantic representation: embeddings, classification, and search tasks. This is where most applied backend problems are actually solved - text search, comparison, automatic classification - not human–model dialogue.

And here it suddenly turned out that there are tools that let you do this directly in PHP, without a Python stack. One of them is TransformersPHP.

It's important to clarify right away: this is not an attempt to turn PHP into Python, nor a universal solution. It's a library for inference - using already trained models.

In my view, TransformersPHP is one of the most interesting and illustrative projects in the modern PHP ML ecosystem. Special thanks to its author, Kyrian Obikwelu, for creating and maintaining it.

In short, it's a library that allows you to use transformer models (BERT, RoBERTa, DistilBERT, and others) directly from PHP - without Python and without external APIs.

Essentially, it's a PHP-oriented wrapper around Hugging Face Transformers ideas, adapted for the PHP ecosystem and real-world use cases.

The Key Feature: Local Inference

Models are loaded and executed inside the PHP application itself (via ONNX Runtime). This opens up important architectural possibilities:

no network calls to LLM APIs
full control over data (important for privacy-sensitive environments)
predictable and stable request latency
offline operation (after the first run and model download)

TransformersPHP supports common NLP tasks such as embeddings, text classification, semantic similarity, and more.

What I Like Most

The most valuable feeling is the absence of context switching.

I stay in PHP. I write the same code. I deploy the same way. I use the same architectural approaches. Nothing changes.

In this setup, the model is not some "magical object", but just another data source. Unusual, yes - but no more mysterious than any other.

And that completely changes your attitude toward the topic. Don't you agree?

Running a Model in 10 Minutes

The first launch is critical.
If it's complicated, that's usually where everything ends.

With TransformersPHP, the feeling is the opposite: it's more like working with a regular dependency.

The full installation guide is available in the documentation.
For simplicity, we'll run everything in Docker with all dependencies included.

Yes, the Dockerfile looks large - but it's one-time infrastructure. The actual launch and first demo really take just a few minutes.

Requirements

PHP 8.1 or higher
Composer
PHP FFI extension
JIT compilation (optional, for performance)
Increased memory limit (for heavier tasks like text generation)

Project Structure

/demo/
  ├── app/
  │    ├── demo.php
  │    ├── semantic-search.php
  ├── docker/
  │    ├── Dockerfile
  ├── docker-composer.yaml
  ├── composer.json

Installation (Docker)

File: docker-compose.yml

networks:
  ai-for-php-developers:
    driver: bridge

services:
  app:
    build:
      context: .
      dockerfile: docker/Dockerfile
    volumes:
      - .:/var/www
    ports:
      - "8088:8088"
    command: php -S 0.0.0.0:8088 -t app
    networks:
      - ai-for-php-developers

File: docker/Dockerfile

FROM php:8.2-fpm

# ------------------------------
# Install system dependencies
# ------------------------------
RUN apt-get update && apt-get install -y \
    libzip-dev \
    zip \
    unzip \
    git \
    libxml2-dev \
    libcurl4-openssl-dev \
    libpng-dev \
    libonig-dev \
    && rm -rf /var/lib/apt/lists/*

# ------------------------------
# Install PHP extensions
# ------------------------------
RUN docker-php-ext-install zip pdo_mysql bcmath xml mbstring curl gd pcntl

# ------------------------------
# Enable FFI
# ------------------------------
RUN apt-get update && apt-get install -y \
    libffi-dev \
    pkg-config \
    && rm -rf /var/lib/apt/lists/*
RUN docker-php-ext-install ffi
RUN echo "ffi.enable=1" > /usr/local/etc/php/conf.d/ffi.ini

# ------------------------------
# Install ONNX Runtime
# ------------------------------
ENV ONNXRUNTIME_VERSION=1.17.1

RUN curl -L https://github.com/microsoft/onnxruntime/releases/download/v${ONNXRUNTIME_VERSION}/onnxruntime-linux-x64-${ONNXRUNTIME\_VERSION}.tgz \
    | tar -xz \
    && cp onnxruntime-linux-x64-${ONNXRUNTIME_VERSION}/lib/libonnxruntime.so* /usr/lib/ \
    && ldconfig \
    && rm -rf onnxruntime-linux-x64-${ONNXRUNTIME_VERSION}

# ------------------------------
# Install Composer
# ------------------------------
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www

# Copy existing application directory contents
COPY . /var/www

# Configure PHP
RUN echo "memory_limit = 512M" >> /usr/local/etc/php/conf.d/docker-php-ram-limit.ini
RUN echo "max_execution_time = 300" >> /usr/local/etc/php/conf.d/docker-php-max-execution-time.ini

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]

File: composer.json

{
  "type": "project",
  "minimum-stability": "stable",
  "prefer-stable": true,
  "require": {
    "codewithkyrian/transformers": "~0.6.2"
  },
  "config": {
    "allow-plugins": {
      "codewithkyrian/platform-package-installer": true
    }
  }
}

Run the Environment

docker compose build --pull
docker compose up -d
docker compose exec app /bin/bash -c "composer install"

The idea is simple: the example should run locally without manual environment setup.

Basic Demo Example

Let's start with the simplest task: sentiment analysis.
If everything above worked correctly, you can run the example below (note that the first run may take a few seconds):

docker compose exec app php app/demo.php

File: app/demo.php

require_once __DIR__ . '/../vendor/autoload.php';

use function Codewithkyrian\Transformers\Pipelines\pipeline;

// Dedicate a sentiment analysis pipeline
$classifier = pipeline('sentiment-analysis');

$out = $classifier(['I love transformers!']);
print_r($out);

$out = $classifier(['I hate transformers!']);
print_r($out);
The result is exactly what you'd expect.
I love transformers!
Array ( 
  [label] => POSITIVE 
  [score] => 0.99978870153427 
)

I hate transformers!
Array ( 
  [label] => NEGATIVE 
  [score] => 0.99863630533218 
)

The purpose of this example is purely psychological: to remove the barrier.
A model in PHP is just another object you can work with.

Architectural Role of TransformersPHP

This library does not compete with large LLM services like GPT or Claude. It covers a different, very important layer:

fast embeddings
local classification
semantic search
lightweight NLP without external dependencies

In combination with PHP, this makes perfect sense. PHP remains the core business-logic layer, while transformers become an embedded tool rather than a remote service.

TransformersPHP is a great example of how modern ML is gradually becoming less "foreign" to PHP and more native to its ecosystem - through careful engineering bridges like ONNX.

Real Case: Semantic Search Over Events

Tutorial examples are nice, but they get boring quickly. Let's look at a task that actually occurs in backend systems.

Run the example:

docker compose exec app php app/semantic-search.php

Scenario

We have events with short textual descriptions. A user searches for:

"sanctions against IT companies"
"space race among countries in the region"

These exact phrases may not appear in the data at all. Traditional keyword search starts to struggle: synonyms, morphology, different languages, hacks on top of hacks.

A Thought Experiment

Suppose we have an event feed like this:

new restrictions introduced against technology corporations
regional countries increase investments in satellite programs
escalation of political conflict in several provinces

Now the user searches: "space race among countries in the region".

None of those words must appear literally. And that's normal - people don't think the way systems store text.

Solution Idea

Instead of guessing words, we search by meaning - in an engineering sense:

event description → vector
user query → vector
find nearest vectors

Embeddings become a universal index of meaning.

Steps

Take events {id, title, description}
Compute embeddings only for description
Embed the user query
Find nearest vectors
Sort and return results

No model training. No complex infrastructure.
Event embeddings are computed once and stored anywhere.
Queries are embedded at search time.

And… voilà.
No model training.
No magic.
Just a different way to represent text.

Operation Logic

We'll place the operation logic in a separate class, SemanticEventSearch. This class doesn't claim to be the best code on the planet, and is written for demonstration purposes only - so we'll omit any comments on its quality.

final class SemanticEventSearch
{
    private string $model = 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
    private string $cachePath;
    private string $defaultQuery = 'санкции против IT-компаний';
    private int $topN;

    private ?string $query = null;

    /** @var list<array{id:int,title:string,description:string}> */
    private array $events;

    /** @var array<int, list<float|int>> */
    private array $eventEmbeddingsById = [];

    private $embedder;

    /**
     * Create a new semantic search instance.
     *
     * @param int $topN Number of results to return.
     */
    public function __construct(int $topN = 3)
    {
        $this->cachePath = __DIR__ . '/../embeddings.events.json';
        $this->events = [];
        $this->embedder = null;
        $this->topN = $topN;
    }

    /**
     * Inject events that will be indexed/searched.
     *
     * @param list<array{id:int,title:string,description:string}> $events
     * @return $this
     */
    public function setEvents(array $events): self
    {
        $this->events = $events;
        $this->eventEmbeddingsById = [];
        return $this;
    }

    /**
     * Set the embeddings model identifier.
     *
     * Switching model invalidates in-memory embeddings.
     *
     * @param string $model
     * @return $this
     */
    public function setModel(string $model): self
    {
        $this->model = $model;
        $this->embedder = null;
        $this->eventEmbeddingsById = [];
        return $this;
    }

    /**
     * Set the query to be searched.
     *
     * @param string $query
     * @return $this
     */
    public function setQuery(string $query): self
    {
        $q = trim($query);
        $this->query = $q === '' ? null : $q;
        return $this;
    }

    /**
     * Run the end-to-end semantic search pipeline (cache -> embed query -> score -> top-N).
     *
     * @return array{query:string,results:list<array{score:float,event:array{id:int,title:string,description:string}}>}
     * @throws RuntimeException If events are not set or embeddings output is unexpected.
     */
    public function run(): array
    {
        if (count($this->events) === 0) {
            throw new RuntimeException('Events list is empty. Call setEvents() before run().');
        }

        if ($this->embedder === null) {
            $this->embedder = pipeline('embeddings', $this->model);
        }

        $this->loadEmbeddingsFromCacheIfCompatible();
        $this->ensureAllEventEmbeddings();

        $query = $this->query ?? $this->defaultQuery;
        $queryVec = $this->embedText($query);

        $results = $this->search($queryVec);
        return [
            'query' => $query,
            'results' => $results,
        ];
    }

    /**
     * Compute an embedding vector for a single text.
     *
     * @param string $text
     * @return list<float|int>
     * @throws RuntimeException
     */
    private function embedText(string $text): array
    {
        $emb = ($this->embedder)($text, normalize: true, pooling: 'mean');
        if (!is_array($emb) || !isset($emb[0]) || !is_array($emb[0])) {
            throw new RuntimeException('Unexpected embeddings output format');
        }

        return $emb[0];
    }

    /**
     * Cosine similarity between two vectors.
     *
     * @param list<float|int> $a
     * @param list<float|int> $b
     * @return float
     */
    private function cosineSimilarity(array $a, array $b): float
    {
        $n = min(count($a), count($b));

        $dot = 0.0;
        $normA = 0.0;
        $normB = 0.0;

        for ($i = 0; $i < $n; $i++) {
            $x = (float) $a[$i];
            $y = (float) $b[$i];

            $dot += $x * $y;
            $normA += $x * $x;
            $normB += $y * $y;
        }

        if ($normA <= 0.0 || $normB <= 0.0) {
            return 0.0;
        }

        return $dot / (sqrt($normA) * sqrt($normB));
    }

    /**
     * Load a JSON file and decode to array.
     *
     * @param string $path
     * @return array|null
     */
    private function loadJsonFile(string $path): ?array
    {
        if (!is_file($path)) {
            return null;
        }

        $raw = file_get_contents($path);
        if ($raw === false) {
            return null;
        }

        $data = json_decode($raw, true);
        return is_array($data) ? $data : null;
    }

    /**
     * Encode and save data to JSON file.
     *
     * @param string $path
     * @param array $data
     * @throws RuntimeException
     */
    private function saveJsonFile(string $path, array $data): void
    {
        $json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
        if ($json === false) {
            throw new RuntimeException('Failed to encode JSON');
        }

        $ok = file_put_contents($path, $json);
        if ($ok === false) {
            throw new RuntimeException('Failed to write cache file: ' . $path);
        }
    }

    /**
     * Load cached event embeddings only if they were produced by the current model.
     *
     * @return void
     */
    private function loadEmbeddingsFromCacheIfCompatible(): void
    {
        $cached = $this->loadJsonFile($this->cachePath);

        if (!is_array($cached) || !isset($cached['model'], $cached['events']) || !is_array($cached['events'])) {
            return;
        }

        if ($cached['model'] !== $this->model) {
            return;
        }

        foreach ($cached['events'] as $row) {
            if (isset($row['id'], $row['embedding']) && is_array($row['embedding'])) {
                $this->eventEmbeddingsById[(int) $row['id']] = $row['embedding'];
            }
        }
    }

    /**
     * Ensure embeddings exist for all events and persist them to cache.
     *
     * @return void
     * @throws RuntimeException
     */
    private function ensureAllEventEmbeddings(): void
    {
        $missing = [];
        foreach ($this->events as $event) {
            $id = (int) $event['id'];
            if (!isset($this->eventEmbeddingsById[$id])) {
                $missing[] = $event;
            }
        }

        if (count($missing) === 0) {
            return;
        }

        foreach ($missing as $event) {
            $id = (int) $event['id'];
            $text = (string) $event['description'];

            $this->eventEmbeddingsById[$id] = $this->embedText($text);
        }

        $toCache = [
            'model' => $this->model,
            'events' => array_values(array_map(
                fn(array $event): array => [
                    'id' => (int) $event['id'],
                    'embedding' => $this->eventEmbeddingsById[(int) $event['id']],
                ],
                $this->events
            )),
        ];

        $this->saveJsonFile($this->cachePath, $toCache);
    }

    /**
     * Score all events against the query embedding and return the top-N results.
     *
     * @param list<float|int> $queryVec
     * @return list<array{score:float,event:array{id:int,title:string,description:string}}>
     */
    private function search(array $queryVec): array
    {
        $scored = [];

        foreach ($this->events as $event) {
            $id = (int) $event['id'];
            $score = $this->cosineSimilarity($queryVec, $this->eventEmbeddingsById[$id]);

            $scored[] = [
                'score' => $score,
                'event' => $event,
            ];
        }

        usort($scored, static fn(array $a, array $b): int => $b['score'] <=> $a['score']);

        return array_slice($scored, 0, $this->topN);
    }

    /**
     * Render results as plain text.
     *
     * @param string $query
     * @param list<array{score:float,event:array{id:int,title:string,description:string}}> $results
     * @return void
     */
    public function render(string $query, array $results): void
    {
        echo "Query: {$query}\n\n";
        foreach ($results as $row) {
            $event = $row['event'];
            $score = (float) $row['score'];

            echo "[" . number_format($score, 4) . "] #{$event['id']} {$event['title']}\n";
            echo "  {$event['description']}\n\n";
        }
    }
}

Data Preparing

Let's assume this is our data, collected from various sources. For simplicity, let's place it in an array.

$events = [
    [
        'id' => 1,
        'title' => 'Restrictions Against Technology Corporations',
        'description' => 'New economic measures have been introduced against major technology companies.',
    ],
    [
        'id' => 2,
        'title' => 'Development of Space Programs',
        'description' => 'Several countries in the region have increased funding for national satellite projects.',
    ],
    [
        'id' => 3,
        'title' => 'Escalation of Political Conflict',
        'description' => 'An escalation of politically motivated conflict has occurred in several provinces.',
    ],
    [
        'id' => 4,
        'title' => 'Restrictions Against the IT Sector',
        'description' => 'The government announced new restrictions for companies operating in the information technology sector.',
    ],
    [
        'id' => 5,
        'title' => 'Rising Inflation and Key Interest Rate Review',
        'description' => 'The central bank raised the key interest rate amid accelerating inflation and rising prices of imported goods.',
    ],
    [
        'id' => 6,
        'title' => 'Launch of a Small Business Support Program',
        'description' => 'Authorities announced preferential loans and tax incentives for small and medium-sized businesses in the regions.',
    ],
    [
        'id' => 8,
        'title' => 'Data Breach in Online Retail',
        'description' => 'An online retailer is investigating a leak of customers' personal data following the compromise of employee accounts.',
    ],
    [
        'id' => 9,
        'title' => 'Medical Breakthrough: New Diagnostic Method',
        'description' => 'Researchers presented a method for early disease diagnosis using biomarkers, significantly reducing analysis time.',
    ],
    [
        'id' => 10,
        'title' => 'Seasonal Increase in Illness Rates',
        'description' => 'Several cities have reported a rise in respiratory infections, with clinics increasing patient intake.',
    ],
    [
        'id' => 12,
        'title' => 'Drought and Risks to Agriculture',
        'description' => 'Due to prolonged drought, farmers predict lower crop yields, and support measures for agriculture are being discussed.',
    ],
    [
        'id' => 13,
        'title' => 'Final of a Major Sports Tournament',
        'description' => 'In the decisive match of the season, the team secured victory in extra time, setting a new attendance record.',
    ],
    [
        'id' => 14,
        'title' => 'Player Transfer and Squad Reinforcement',
        'description' => 'The club signed a new striker, aiming to strengthen its attacking line ahead of a series of derby matches.',
    ],
    [
        'id' => 15,
        'title' => 'New Rules for Marketplaces',
        'description' => 'The regulator proposed requirements for product labeling and commission transparency on online trading platforms.',
    ],
    [
        'id' => 17,
        'title' => 'Disruptions in Semiconductor Supply',
        'description' => 'Electronics manufacturers warned of chip supply delays due to export restrictions and factory overloads.',
    ],
    [
        'id' => 18,
        'title' => 'Opening of a Contemporary Art Festival',
        'description' => 'A contemporary art festival has opened in the capital, featuring exhibitions, performances, and artist lectures.',
    ],
    [
        'id' => 19,
        'title' => 'Major Deal in the Real Estate Market',
        'description' => 'An investment fund acquired a portfolio of commercial real estate, planning renovation and improved energy efficiency.',
    ],
    [
        'id' => 20,
        'title' => 'Ocean Research and New Findings',
        'description' => 'A scientific expedition collected data on ocean currents and water temperature, refining climate change forecasts.',
    ],
];

Run the example

It's simple here: just run our code and wait for the results.

require_once __DIR__ . '/../vendor/autoload.php';

use function Codewithkyrian\Transformers\Pipelines\pipeline;

final class SemanticEventSearch {...}

$events = [...];

$query = 'sanctions against IT companies';

$search = new SemanticEventSearch(topN: 3);
$search->setModel('Xenova/paraphrase-multilingual-MiniLM-L12-v2');
$search->setEvents($events);
$search->setQuery($query);
$out = $search->run();
$search->render($out['query'], $out['results']);

Result

The output matches by meaning, not words. The first result is the most suitable for the population with our request.

Query: sanctions against IT companies
[0.4288] #4 Restrictions against the IT sector
  The government announced new restrictions for companies operating in the IT industry.
[0.3356] #15 New rules for marketplaces
  The regulator proposed requirements for product labeling and commission transparency.
[0.2598] #8 Data breach in online retail
  An online store investigates a customer data leak after account compromise.

Production Use Cases

This already looks like a product approach, not an experiment.
And it has useful properties:

weak dependence on exact wording
works well with short texts
easily combined with classic filters (date, region, type)

This is not "AI for the sake of AI", but practical, explainable, debuggable logic.

Limitations and Caveats

This is not a silver bullet.

Models are large. Performance matters. Some problems are still better solved with plain SQL.

But that's a normal engineering discussion - about trade-offs, not magic or black boxes.

Where to Go Next

For me, TransformersPHP is a strong example that AI can be used directly in PHP projects without changing the stack or introducing Python.

In my open and free book "AI for PHP Developers", I explore similar cases: when it makes sense, how to choose models, and how not to turn a project into a collection of experimental features.

All examples can be downloaded and run using a ready-made Docker environment from GitHub repository:
https://github.com/apphp/ai-for-php-developers-examples

You can also run all examples from the book directly:
https://aiwithphp.org/books/ai-for-php-developers/examples

If the topic resonates - I'd be glad to discuss and get feedback.
Especially interesting to hear what tasks you already solve (or want to solve) with AI in PHP projects.

Machine Learning Ecosystem in PHP

Samuel Akopyan — Thu, 25 Dec 2025 15:02:19 +0000

The PHP Machine Learning Ecosystem: A Practical Overview

When people say “there is no machine learning in PHP”, they usually mix up two very different things.

It’s true that PHP is rarely used to train large neural networks from scratch. But PHP has been living comfortably for years in the world of model application, vector operations, statistics, classification, embeddings, and numerical computing.

The PHP ML ecosystem is not loud — but it is mature.

It consists of four layers:

Classical ML libraries
Mathematical foundations
Integration tools for modern ML systems
Integration with external ML services

Let’s walk through them step by step.

Classical Machine Learning in PHP

We’ll start with libraries that implement ML algorithms directly in PHP, without calling external services.

PHP-ML

Repository:
https://github.com/jorgecasas/php-ml
Status: Mostly unmaintained

PHP-ML is the traditional entry point into machine learning with PHP. It contains the full classic ML toolbox:

k-Nearest Neighbors
Linear and logistic regression
Naive Bayes
Support Vector Machines
Decision trees
k-means clustering

The philosophy of PHP-ML is important to understand. It does not try to compete with PyTorch or scikit-learn in performance. Its goal is clarity.

The code is easy to read, easy to debug, and easy to explain. From a learning and educational perspective, this is a huge advantage.

A typical use case looks like this:

You extract features from a database
Train a simple classification or regression model
Serialize it
Use it at runtime without any external ML service

The resulting code feels almost textbook-like — and that’s a feature, not a bug. You can reason about the model and explain the math behind it without hidden magic.

The example looks almost textbook:

use Phpml\Classification\KNearestNeighbors;

$classifier = new KNearestNeighbors();
$classifier->train($samples, $labels);

$result = $classifier->predict([3, 7]);

And this is, in fact, a huge plus. The code is transparent, the model can be debugged, and the mathematical meaning of the algorithm is easy to explain.

If PHP-ML is a textbook, then the next library is an engineering tool.

Rubix ML

Website & Repository:
https://github.com/RubixML
Status: Actively maintained

Rubix ML is a full-featured ML framework for PHP. It focuses on production-grade pipelines, not demos.

Key features include:

Classification, regression, clustering
First-class Dataset objects
Transformers and feature scaling
Model serialization
Reproducible pipelines

Let's see how this works in practice.
Let's say we have data for binary classification.

use Rubix\ML\Datasets\Labeled;
use Rubix\ML\Classifiers\KNearestNeighbors;

$samples = [
    [170, 65],
    [160, 50],
    [180, 80],
    [175, 70],
];

$labels = ['M', 'F', 'M', 'M'];

$dataset = new Labeled($samples, $labels);

$model = new KNearestNeighbors(3);
$model->train($dataset);

$prediction = $model->predict([[172, 68]]);

One important design decision stands out:
You don’t pass raw arrays into models — you work with structured datasets.

This enforces a mental shift from “script hacking” to “ML engineering”.

Rubix is often chosen when a model is not an experiment, but a long-lived part of a production system, where versioning, repeatability, and stability matter.

Linear Algebra and Numerical Foundations

All machine learning eventually boils down to vectors, matrices, and tensors. PHP has several solid options here.

RubixML/Tensor

Repository:
https://github.com/RubixML/Tensor
Status: Active

RubixML/Tensor is a low-level linear algebra library optimized specifically for ML workloads.

It provides:

Tensors and matrices
Element-wise operations
Decompositions and transformations

If Rubix ML is the brain, Tensor is the muscle.

This library is crucial when you care about predictable memory usage and performance, not just correctness.

MathPHP

Repository:
https://github.com/markrogoyski/math-php
Status: Active

MathPHP is a general-purpose mathematical library written in pure PHP.

It includes:

Linear algebra
Statistics
Probability distributions
Numerical methods

In ML projects, MathPHP is often used as a supporting foundation: distance metrics, normalization, statistical estimates, hypothesis testing.

It’s especially valuable because it implements math honestly — without hidden optimizations or abstractions.

NumPower

Repository:
https://github.com/RubixML/numpower
Status: Active

NumPower is a special case.

It’s a PHP extension for high-performance numerical computing, inspired by NumPy. It uses AVX2 instructions on x86-64 CPUs and supports CUDA for GPU computation.

This answers a common question:

“Can PHP do real scientific computing?”

Yes — if you’re willing to use extensions and specialized infrastructure.

NumPower is relevant when PHP is not just a web layer, but a computational engine.

NumPHP and SciPhp

NumPHP: https://numphp.org
SciPhp: https://sciphp.org Status: Unmaintained

These NumPy-inspired libraries are mostly of historical interest today. They show that scientific computing ideas in PHP existed long before the current AI hype.

Modern ML Integrations: Tokens, Embeddings, Data Pipelines

Modern ML rarely lives in isolation. Around every model, there’s infrastructure.

tiktoken-php

Repository:
https://github.com/yethee/tiktoken-php
Status: Active

tiktoken-php is a PHP port of OpenAI’s tokenizer.

It allows you to:

Count tokens
Split text correctly
Estimate request costs
Control context length

If you work with GPT, Claude, or Gemini from PHP, this library is almost mandatory.

Rindow Math Matrix

Repository:
https://github.com/rindow/rindow-math-matrix
Status: Active

A linear algebra library focused on ML and numerical methods, often used within the Rindow ecosystem.

A good choice if you want strict mathematical APIs and precise control over numerical behavior.

Flow PHP

Repository:
https://github.com/flow-php/flow
Status: Active

Flow PHP is not an ML library — it’s a data processing framework.

It handles:

ETL pipelines
Data transformations
Validation
Streaming workflows

In real ML systems, data preparation is often harder than modeling. Flow PHP fills the gap between “raw data exists” and “the model can consume it”.

Integration with External ML Services

The most common way to use ML in PHP today is inference via APIs.

LLM APIs: OpenAI, Anthropic, Gemini

PHP SDKs and HTTP clients allow PHP applications to consume:

Embeddings
Classification
Text generation
Summarization
Structured data extraction

Architecturally, this means:

The model lives elsewhere
PHP controls when and why it’s used

This plays perfectly to PHP’s strengths: queues, databases, caching, billing, UI, and orchestration.

ONNX Runtime and Model Inference

ONNX deserves special mention.

Models can be trained in Python, exported to ONNX, and executed from PHP via extensions or external runtimes.

This is a rare but powerful setup:
no Python in production, but full control over inference inside PHP applications.

Computer Vision and Signal Processing

PHP is not a leader here, but basic tooling exists.

OpenCV can be used via bindings or CLI calls, with PHP acting as the orchestration layer. This pattern is typical: PHP doesn’t do the heavy math — it coordinates it.

How to Read the PHP ML Ecosystem as a Whole

One key conclusion matters.

PHP is not a language for ML benchmarks or Kaggle competitions.

It’s a language for connecting machine learning to real products.

Its ML ecosystem prioritizes:

Code clarity
Integration
Data control
Predictable behavior

If you understand the math behind a model, PHP gives you enough tools to use it in production.

In that sense, PHP’s ML ecosystem is not weak — it’s honest and practical.

PHP and machine learning are about roles in a system:

Applying models
Working with embeddings and vectors
Classification and ranking
Orchestrating ML services
Connecting math with business logic

That’s why PHP’s ML ecosystem isn’t a monolith — it’s a precise toolbox.

And for many real-world systems, that’s exactly what you want.

For a broader view of the PHP machine learning ecosystem and ongoing experiments, you can explore Awesome PHP ML—a curated collection of libraries, tools, and projects focused on machine learning in PHP. It’s a great starting point for discovering what’s currently available and actively developed:
https://github.com/apphp/awesome-php-ml

Introducing PrettyPrint — a PHP array pretty-printer with Python-/PyTorch-style formatting

Samuel Akopyan — Sat, 22 Nov 2025 15:46:46 +0000

I'm excited to announce PrettyPrint, a small, zero-dependency PHP utility designed to format numeric arrays in a clean, readable style inspired by Python and the tensor-views you’ll see in PyTorch.

Whether you're doing ML experiments, debugging data pipelines, logging arrays, or building educational tools, PrettyPrint makes it easier to inspect array data in a structured way.

Why use PrettyPrint?

No extra dependencies - just pure PHP.

Supports aligned 2D tables, summarized tensor-style views (for larger arrays), 3D tensor with head/tail blocks, and flexible output options (labels, controlling newline behaviour, etc.).

Makes your array dumps more readable and visually helpful.

Quick Start & Examples

Installation

composer require apphp/pretty-print

Global helper functions

You can use the pprint() helper function for quick prints:

Print scalars/strings

pprint('Hello', 123, 4.56);
// Output:
// Hello 123 4.5600

1D / 2D examples

// Print multiple 1D rows aligned as a 2D table
pprint([1, 23, 456], [12, 3, 45]);
// Output:
// [[  1,  23, 456],
//  [12,   3,  45]]

Label + 2D matrix

pprint('Confusion matrix:', [[1,23], [456,7]]);
// Output:
// Confusion matrix:
// [[   1,  23],
//  [ 456,   7]]

Tensor / summarization example

$matrix = [
    [1, 2,  3,  4,  5],
    [6, 7,  8,  9, 10],
    [11,12, 13, 14, 15],
];
pprint($matrix);
// Output:
// tensor([
//   [  1,   2,   3,   4,   5],
//   [  6,   7,   8,   9,  10],
//   [ 11,  12,  13,  14,  15]
// ])

And for summarization (showing just head + tail of rows/cols):

pprint($matrix, headRows:1, tailRows:1, headCols:2, tailCols:2);
// Output:
// tensor([
//   [  1,   2,  ...,   4,   5],
//   ...,
//   [ 11,  12,  ...,  14,  15]
// ])

You can even print 3D tensor-like structures with summarised blocks:

$tensor3d = [
    [[1,2,3],[4,5,6]],
    [[7,8,9],[10,11,12]],
    [[13,14,15],[16,17,18]],
];
pprint($tensor3d, headB:1, tailB:1, headRows:1, tailRows:1, headCols:1, tailCols:1);
// Output:
// tensor([
//  [[ 1,  ...,  3],
//   [ 4,  ...,  6]],
//
//  ...,
//
//  [[13,  ..., 15],
//   [16,  ..., 18]]
// ])

Object-style usage

If you prefer, you can instantiate the printer as an object:

use Apphp\PrettyPrint\PrettyPrint;

$pp = new PrettyPrint();
$pp('Hello', 42);       // same as pprint('Hello', 42)

$pp($tensor3d, headB:2, tailB:1, headRows:1, tailRows:1, headCols:1, tailCols:1);
$pp('Metrics:', [[0.91, 0.02], [0.03, 0.88]]);

Options reference

Here are a few of the core options you can pass:

end (string) — line terminator (default: newline)
headB / tailB (ints) — number of 2D blocks shown for 3D tensors
headRows / tailRows — number of head/tail rows per slice with ellipsis between
headCols / tailCols — number of head/tail columns per slice with ellipsis between

Named-argument syntax (PHP 8+) is supported, or you can pass an array of options as last parameter.

Where it shines

ML/AI workflows: When you have numeric arrays or tensors in PHP (or imported from elsewhere) and want human-readable dumps.

Debugging & logging: Replace ad-hoc var_dump() or print_r() with structured, aligned table views.

Educational/teaching code: When showing matrix/tensor examples and you want a cleaner presentation.

CLI & scripts: For quick visual inspection of matrices/tensors in terminal output.

Final thoughts

I believe PrettyPrint fills a small but useful niche for PHP developers working with numeric data or coming from Python/PyTorch mindsets - offering readability, alignment, summarization, and minimal overhead.

Give it a spin:

GitHub: https://github.com/apphp/pretty-print
Packagist: https://packagist.org/packages/apphp/pretty-print

I'd love your feedback, suggestions for enhancements, or contributions — open an issue or PR and let’s make this tool even better together!

Happy coding!

Building a simple RAG system in PHP with the Neuron AI framework in one evening

Samuel Akopyan — Sat, 15 Nov 2025 20:58:11 +0000

RAG (Retrieval-Augmented Generation) is an AI method that combines a large language model (LLM) with an external knowledge base to produce more accurate, context-aware answers. The idea is simple: first we retrieve relevant information from documents or data sources, then we pass this information to an LLM to generate the final response. This approach reduces hallucinations, improves accuracy, and allows you to update the knowledge base without expensive retraining.

Today, we’ll look at how to build a basic RAG system in PHP (yes, really!) using the Neuron AI framework. This will be a small proof-of-concept: minimal, but fully functional.

Ready to generate something useful?

1. What RAG Is and Why You Need It

In short: RAG helps an AI system avoid guessing by fetching real data before generating an answer.

The classical flow has two steps:

Retrieval — find relevant document chunks using vector search.
Generation — create an answer using the retrieved data.

There are many variations of RAG — from simple “vector search + LLM” to complex systems with re-ranking, context caching, and chain-of-thought (better not use that in production). If you want a deep dive, the internet is full of good articles explaining the history and evolution of RAG (the approach started taking shape around 2020).

Typical Use Cases

internal chatbots for documentation search
voice assistants
helpdesk support bots
or simply impressing your colleagues

2. Why PHP and Neuron AI?

Good question.

Of course, you can build RAG in Python using LangChain, LlamaIndex, Milvus, Chroma, etc. There are plenty of tutorials. But if your whole web project already runs on PHP, why bring in Python just for vector search?

Neuron AI is a lightweight PHP framework that brings embeddings, LLMs, and even a local VectorStore into the PHP world. I wrote about it earlier, and this article continues with a real, practical example.

It’s simple, easy to integrate, and fits naturally into existing PHP applications — very much in the spirit of Laravel, but for AI.

3. What We’re Building

We’ll create an AI agent that can answer questions using your internal knowledge base.

Technically, we’ll build a basic RAG system that:

creates a vector store from documents
searches relevant chunks (returns the top-K closest vectors)
generates an answer using the retrieved data

Imagine you have internal Wiki or Confluence docs and want a bot that can answer questions about them. This is exactly what RAG was designed for — especially useful for newcomers who still see your documentation as “Terra Incognita”.

4. Step-by-Step with Code

4.1 Requirements

PHP 8.2+
Composer
Neuron AI (composer require neuron-ai/neuron)
LLM API key (OpenAI, etc.)

4.2 Why FileVectorStore?

For this example, we won’t use vector databases like Faiss or Pinecone. A simple FileVectorStore is enough — it stores everything in a .store file.

It’s not scalable, but perfect for demos or small local projects with a few thousand documents.

4.3 Installation and Setup

Install packages:

composer require neuron-ai/neuron
composer require openai-php/laravel

Project structure:

/demo/
  ├── store/
  │    ├── docs/
  ├── src/
  │    ├── Commands/
  │    ├── Classes/
  └── index.php

4.4 Preparing the Documents

Place four Markdown documents inside store/docs/:

company-culture.md
company-overview.md
services-portfolio.md
technical-expertise.md

They describe a company: culture, overview, services, and technical expertise.

4.5 Creating the VectorStore

Example class: src/Classes/PopulateVectorStore.php

namespace App\demo\src\Classes;
require_once __DIR__ . '/../../../../vendor/autoload.php';

use NeuronAI\RAG\DataLoader\FileDataLoader;
use OpenAI\Factory;

class PopulateVectorStore {
    public static function populate(): void {
        $vectorDir = __DIR__ . '/../../store';
        $storeFile = $vectorDir . '/demo.store';
        $metaFile = $vectorDir . '/demo.meta.json';

        // Ensure directory exists
        if (!is_dir($vectorDir)) {
            mkdir($vectorDir, 0755, true);
        }

        // Clear existing store
        file_put_contents($storeFile, '');

        // Initialize OpenAI client
        $apiKey ='<your-OPENAI_API_KEY-here>';
        if (!is_string($apiKey) || trim($apiKey) === '') {
            throw new \RuntimeException('OpenAI API key not configured. Ensure OPENAI_API_KEY is set.');
        }
        $client = (new Factory())
            ->withApiKey($apiKey)
            ->make();

        $model = 'text-embedding-3-small';

        // Probe expected dimension once
        $expectedDim = 1536;

        // Docs
        $documents = FileDataLoader::for($vectorDir . '/docs')->getDocuments();

        $written = 0;
        // Generate embeddings and write to store
        foreach ($documents as $document) {
            $content = $document->getContent();

            // Get embedding from OpenAI
            try {
                $response = $client->embeddings()->create([
                    'model' => $model,
                    'input' => $content,
                    'dimensions' => $expectedDim,
                ]);

                // SDK v0.12+ exposes embeddings via `$response->embeddings`
                if (isset($response->embeddings[0]->embedding)) {
                    $embedding = $response->embeddings[0]->embedding;
                } else {
                    // Fallback for array casting if SDK shape changes
                    $arr = method_exists($response, 'toArray') ? $response->toArray() : [];
                    if (isset($arr['data'][0]['embedding'])) {
                        $embedding = $arr['data'][0]['embedding'];
                    } else {
                        throw new \RuntimeException('Unable to parse embedding from OpenAI response');
                    }
                }
            } catch (\Throwable $e) {
                throw new \RuntimeException('Failed to generate embedding: ' . $e->getMessage());
            }

            // Normalize and validate embedding
            if (!is_array($embedding)) {
                echo "! Skipped document due to invalid embedding type.\n";
                continue;
            }
            $embedding = array_map(static function ($v) {
                return is_numeric($v) ? (float)$v : 0.0;
            }, $embedding);

            if (count($embedding) !== $expectedDim) {
                echo "! Skipped document due to dimension mismatch (got " . count($embedding) . ", expected $expectedDim).\n";
                continue;
            }

            // Write as JSON line to store file (strict JSONL)
            // FileVectorStore expects all fields at top level
            $jsonLine = json_encode([
                'embedding' => $embedding,
                'content' => $content,
                'sourceType' => $document->getSourceType(),
                'sourceName' => $document->getSourceName(),
                'id' => md5($content),
                'metadata' => [],
            ], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

            file_put_contents($storeFile, $jsonLine . "\n", FILE_APPEND);
            $written++;

            echo "✓ Added embedding ($written) for: " . $storeFile . " | " . str_replace("\n", ' ', substr(trim($content), 0, 70)) . "...\n";
        }

        // Write metadata file for consistency checks
        $meta = [
            'model' => $model,
            'dimension' => $expectedDim,
            'generatedAt' => date(DATE_ATOM),
            'count' => $written,
        ];
        file_put_contents($metaFile, json_encode($meta, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT));

        echo "\n✓ Vector store populated with $written documents (dimension: $expectedDim)\n";
    }
}

Run the script via index.php:

use App\demo\src\Classes\PopulateVectorStore;

require_once __DIR__ . '/src/Classes/PopulateVectorStore.php';

PopulateVectorStore::populate();

You should see logs like:

php app/demo/index.php
✓ Added embedding (1) for: /app/demo/src/Commands/../../store/demo.store | # Linx Team - Company Culture & Values  ## Core Values  ### Innovation...
✓ Added embedding (2) for: /app/demo/src/Commands/../../store/demo.store | ## Work Environment  ### Remote-Friendly We offer flexible work arrang...
✓ Added embedding (3) for: /app/demo/src/Commands/../../store/demo.store | ## Benefits  ### Competitive Compensation We offer competitive salarie...
✓ Added embedding (4) for: /app/demo/src/Commands/../../store/demo.store | # Linx Team - Company Overview  ## About Us Linx Team is a leading sof...
✓ Added embedding (5) for: /app/demo/src/Commands/../../store/demo.store | # Linx Team - Services & Portfolio  ## Services Offered  ### Custom So...
✓ Added embedding (6) for: /app/demo/src/Commands/../../store/demo.store | ### DevOps & Infrastructure Managing cloud infrastructure, implementin...
✓ Added embedding (7) for: /app/demo/src/Commands/../../store/demo.store | # Linx Team - Technical Expertise  ## Core Technologies  ### Backend D...
✓ Added embedding (8) for: /app/demo/src/Commands/../../store/demo.store | js** - React framework with server-side rendering  ### Cloud & DevOps ...

✓ Vector store populated with 8 documents (dimension: 1536)

Two new files will appear:

demo.meta.json — metadata
demo.store — actual vector entries

Let's take a look at demo.meta.json - everything is clear here.

{
    "model": "text-embedding-3-small",
    "dimension": 1536,
    "generatedAt": "2025-11-15T13:28:53+00:00",
    "count": 8
}

and in demo.store we will see the following:

{"embedding":[-0.02263086,-0.007472924,0.029841794,...],"content":"# Linx Team - ... ","sourceType":"files","sourceName":"company-culture.md","id":"28b40662dad319d6f5718881af03283b","metadata":[]}
{"embedding":[-0.023948364,0.009718814,0.06337647,...],"content":"## Work Enviro ... ","sourceType":"files","sourceName":"company-culture.md","id":"b96cd133b0df26e64b95acdad75c87dd","metadata":[]}
{"embedding":[-0.018617272,0.00053190015,0.095444225,...],"content":"## Benefits\n\n### ...","sourceType":"files","sourceName":"company-culture.md","id":"42041e1af0580a58ae07d6523649b1a9","metadata":[]}
{"embedding":[-0.04209091,-0.006933485,0.03687242,...],"content":"# Linx Team - Company ...","sourceType":"files","sourceName":"company-overview.md","id":"8622e016e3fbeccc8dc10bf9a3a851a6","metadata":[]}
{"embedding":[-0.026189856,-0.0032917524,0.05449412,...],"content":"# Linx Team - Services ...","sourceType":"files","sourceName":"services-portfolio.md","id":"acc30742cf9f55588db5275c4feba183","metadata":[]}
{"embedding":[0.0018354928,-0.009989895,0.04954025,...],"content":"### DevOps & ...","sourceType":"files","sourceName":"services-portfolio.md","id":"d32de0136fdd56991a8ab738c49558a2","metadata":[]}
{"embedding":[-0.06210507,-0.015794381,0.038876604,...],"content":"# Linx Team - ...","sourceType":"files","sourceName":"technical-expertise.md","id":"dff18ab4ded5f65154cdd6e81c49318c","metadata":[]}
{"embedding":[-0.02210143,0.016823476,0.038901344,...],"content":"js** - React framework ...","sourceType":"files","sourceName":"technical-expertise.md","id":"a167473a1d4eeac021fbe9bf2ccd0726","metadata":[]}

Each line in demo.store is a JSON object:

{
  "embedding": [...],
  "content": "....",
  "sourceType": "files",
  "sourceName": "company-culture.md",
  "id": "28b40662dad319d6f5718881af03283b",
  "metadata": []
}

Why 8 entries from 4 documents?

Because the documents are automatically split into chunks before generating embeddings. Each chunk gets its own vector.

Reasons:

embeddings work best on short, coherent text pieces
LLMs have token limits
retrieval becomes more precise

The dimension: 1536 value comes from the OpenAI embedding model (text-embedding-3-small).

4.6 Creating the ChatBot

Create the agent class: src/Commands/ChatBot.php.

<?php

namespace App\demo\src\Commands;
require_once __DIR__ . '/../../../../vendor/autoload.php';

use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAI\OpenAI;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\OpenAIEmbeddingsProvider;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\FileVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class ChatBot extends RAG
{
    private string $apiKey ='<your-OPENAI_API_KEY-here>';
    private string $model = 'gpt-4o-mini';

    protected function provider(): AIProviderInterface
    {
        if (!$this->apiKey) {
            throw new \Exception('OPENAI_API_KEY environment variable is not set');
        }

        return new OpenAI(
            $this->apiKey,
            $this->model,
        );
    }

    protected function embeddings(): EmbeddingsProviderInterface
    {
        if (!$this->apiKey) {
            throw new \Exception('OPENAI_API_KEY environment variable is not set');
        }

        return new OpenAIEmbeddingsProvider(
            key: $this->apiKey,
            model: 'text-embedding-3-small',
            dimensions: 1536
        );
    }

    protected function vectorStore(): VectorStoreInterface
    {
        $vectorDir = __DIR__ . '/../../store';

        // Ensure the vectors directory exists
        if (!is_dir($vectorDir)) {
            mkdir($vectorDir, 0755, true);
        }

        // Ensure the store file exists with at least one empty line to prevent parsing errors
        $storeFile = $vectorDir . '/demo.store';
        if (!file_exists($storeFile) || filesize($storeFile) === 0) {
            // Create an empty store file - FileVectorStore will populate it when documents are added
            file_put_contents($storeFile, '');
        }

        return new FileVectorStore(
            directory: $vectorDir,
            name: 'demo',
            topK: 3
        );
    }
}

Then update your index.php to run the chatbot:

use App\demo\src\Classes\PopulateVectorStore;
use App\demo\src\Commands\ChatBot;
use NeuronAI\Chat\Messages\UserMessage;

require_once __DIR__ . '/../../vendor/autoload.php';

// Populate the vector store if it doesn't exist
$storeFile = __DIR__ . '/store/demo.store';
if (!file_exists($storeFile) || filesize($storeFile) === 0) {
    PopulateVectorStore::populate();
    echo "Vector store populated successfully.\n";
} else {
    echo "Vector store found, start handling...\n";
}

$chatBot = ChatBot::make();
$response = $chatBot->chat(
    new UserMessage('How many employees and managers does the company have?')
);

echo "\n" . $response->getContent() . "\n";

Example output:

The company has over 27 employees and 2 managers, making a total of more than 29 team members.

Another example question

new UserMessage(
   'How many employees and managers does the company have? ' .
   'Provide links to most relevant documents.'
);

returns not only the answer but also recommended documents:

The company has over 27 employees and 2 managers.
For more detailed information, you can refer to the following documents:

Company Overview: company-overview.md
Company Culture: company-culture.md

About topK: 3

topK determines how many closest vectors to return from the vector store. More chunks = richer context, but also slower queries.

So, after all this, the final structure of the project looks like this:

/demo/
  ├── store/
  │    ├── docs/
  │    │    ├── company-culture.md
  │    │    ├── company-overview.md
  │    │    ├── services-portfolio.md
  │    │    ├── technical-expertise.md
  │    │    ├── ...
  │    ├── demo.meta.json
  │    ├── demo.store
  ├── src/
  │    ├── Commands/
  │    │    ├── ChatBot.php
  │    ├── Classes/
  │    │    ├── PopulateVectorStore.php
  └── index.php

5. What Can Be Improved

This was just a basic example. You can add:

real databases (PostgreSQL, Pinecone, Qdrant)
automatic indexing of new Wiki pages
caching for common questions
request logging for analytics and debugging

6. Advanced Version: Add Re-Ranking

For higher accuracy, add document re-ranking using a model like bge-reranker-base. Neuron AI supports this, and the improvement in answer quality is quite noticeable.

7. Modular Architecture: When You Need It

If RAG is just a small feature, keep things simple.
But if the project grows, separate:

VectorStoreService
EmbeddingPipeline
RAGPipeline
ChatController

This lets you switch components easily — e.g., move from OpenAI to Ollama, or from FileVectorStore to Qdrant.

8. Conclusion

RAG is not magic — it’s a clear, well-defined pattern.
Neuron AI finally lets PHP developers play with modern AI tools without switching to Python, Docker, or extra servers.

Yes, FileVectorStore is basic, but perfect for demos and local experiments. Once you understand the principles, you can integrate RAG into any PHP framework and upgrade the components whenever you’re ready.