TransformersPHP Documentation

TransformersPHP is a toolkit for PHP developers to integrate machine learning capabilities directly into PHP applications. It allows you to run pre-trained models locally on your server without relying on external APIs or services.

Key features:

• Local Inference: Models run on your own hardware/server.
• Pre-trained Model Support: Uses models already trained on massive datasets for tasks like text summarization, translation, and sentiment analysis.
• ONNX Runtime Integration: Uses the ONNX (Open Neural Network Exchange) format, allowing models from PyTorch, TensorFlow, JAX, and others to run efficiently in PHP.
• Compatibility: Most models prepared for Xenova/transformers (JavaScript) are compatible with TransformersPHP.

A tensor is a multidimensional array used for numerical computing and machine learning. In TransformersPHP, the Tensor class uses a C-based buffer for high-performance element-wise and mathematical operations.

Performance and Backends

• OpenBLAS: Automatically included in the package for fast mathematical operations. No separate installation is required.
• OpenMP: Can be installed separately to enable parallel computation across multiple CPU cores.
• Fallback: If OpenBLAS is unavailable, the library falls back to a PHP-based buffer, which is slower but remains functional.

Pipelines are a high-level abstraction designed to simplify machine learning tasks. They encapsulate the entire workflow required for Natural Language Processing (NLP), including:

1. Input Preprocessing: Converting raw text into a format the model understands.
2. Model Execution: Running the model inference.
3. Post-processing: Converting model outputs back into human-readable formats (e.g., labels, scores, or translated text).

This allows developers to integrate advanced NLP capabilities without manually managing model weights or tokenization logic.

The output of a text-generation pipeline is an array of associative arrays. Each element corresponds to an input and contains a generated_text key.

If you are building a chat interface, you should append the generated content back to your message history using the assistant role to maintain context for subsequent turns.

Output Format:

[
    ["generated_text" => "...generated content..."]
]

$output = $generator($input, maxNewTokens: 256, returnFullText: false);

// Extract the generated string
$generatedMessage = $output[0]['generated_text'];

// Append to conversation history
$messages[] = ['role' => 'assistant', 'content' => $generatedMessage];

The ASR pipeline returns an array. The structure depends on whether timestamps were requested via returnTimestamps.

Default Output

If no timestamps are requested, the output contains only the transcribed text:

[
  "text" => "Transcribed text here..."
]

Chunk-Level Timestamps

If returnTimestamps is set to true, the output includes a chunks array with timestamps for segments of text:

[
  "text" => "Transcribed text...",
  "chunks" => [
    [
      "timestamp" => [0.0, 5.12],
      "text" => "First chunk of text"
    ],
    // ...
  ]
]

Word-Level Timestamps

If returnTimestamps is set to 'word', the chunks array contains individual words and their specific timestamps:

[
  "text" => "...",
  "chunks" => [
    ["text" => "We,", "timestamp" => [0.6, 0.94]],
    ["text" => "the", "timestamp" => [0.94, 1.3]],
    // ...
  ]
]

The output of the audio classification pipeline is an array of classification results. Each result contains:

• label: The classification label (the specific names depend on the model used).
• score: The confidence score, a value between 0 and 1 (where 1 is the highest confidence).

If topK is greater than 1, the output is an array of these associative arrays. If processing multiple audio files, the structure may vary depending on the specific implementation context, but typically returns the labels and scores for the inputs.

// Example output for topK: 4
[
    ['label' => 'Cat Meow',  'score' => 0.8456],
    ['label' => 'Domestic Animal',  'score' => 0.1234],
    ['label' => 'Pet',  'score' => 0.0987],
    ['label' => 'Mammal',  'score' => 0.0567]
]

Text generation is a task where models produce sequences of text based on an input prompt. Unlike classification (assigning labels) or Named Entity Recognition (identifying entities), generation involves creating novel, coherent, and contextually relevant content such as stories, answers, or summaries.

Models often include a generation_config.json file in their repository which provides default settings optimized for that specific model. These defaults are applied automatically when the model instance is created, but can be overridden during invocation for dynamic control.

The translation pipeline returns an array of arrays. Each inner array corresponds to one input text and contains a single key: translated_text.

If you pass a single string, the result will be an array containing one element. If you pass an array of strings, the output array will have the same number of elements as the input.

// Example output structure for a single input
[
  [
    'translated_text' => 'The United Nations chief says there is no military solution in Syria'
  ]
]

The output of the image-feature-extraction pipeline is a feature vector. The shape of this vector depends on whether pooling is enabled:

Without Pooling (pool: false)

The output shape is typically [X, Y, Z]:

• X: Batch size (e.g., 1 for a single image).
• Y: Sequence length or number of patches/tokens.
• Z: The size of the feature vector per patch. Example (ViT architecture): [1, 197, 768]

With Pooling (pool: true)

The output shape is typically [X, Z]:

• X: Batch size.
• Z: The size of the single pooled feature vector representing the entire image. Example: [1, 768]