Extend Hugging Face support and fix/update examples

Author: chr-hertel

README.md

@@ -34,11 +34,3 @@ Help Symfony by [sponsoring](https://symfony.com/sponsor) its development!
 ## Contributing
 
 Thank you for considering contributing to Symfony AI! You can find the [contribution guide here](CONTRIBUTING.md).
-
-## Fixture Licenses
-
-For testing multi-modal features, the repository contains binary media content, with the following owners and licenses:
-
-* `tests/Fixture/image.jpg`: Chris F., Creative Commons, see [pexels.com](https://www.pexels.com/photo/blauer-und-gruner-elefant-mit-licht-1680755/)
-* `tests/Fixture/audio.mp3`: davidbain, Creative Commons, see [freesound.org](https://freesound.org/people/davidbain/sounds/136777/)
-* `tests/Fixture/document.pdf`: Chem8240ja, Public Domain, see [Wikipedia](https://en.m.wikipedia.org/wiki/File:Re_example.pdf)

examples/huggingface/README.md

@@ -0,0 +1,128 @@
+# Symfony Hugging Face Examples
+
+This directory contains various examples of how to use the Symfony AI with [Hugging Face](https://huggingface.co/)
+and sits on top of the [Hugging Face Inference API](https://huggingface.co/inference-api).
+
+The Hugging Face Hub provides access to a wide range of pre-trained open source models for various AI tasks, which you
+can directly use via Symfony AI's Hugging Face Platform Bridge.
+
+## Getting Started
+
+Hugging Face offers a free tier for their Inference API, which you can use to get started. Therefore, you need to create
+an account on [Hugging Face](https://huggingface.co/join), generate an
+[access token](https://huggingface.co/settings/tokens), and add it to your `.env.local` file in the root of the
+examples' directory as `HUGGINGFACE_KEY`.
+
+```bash
+echo 'HUGGINGFACE_KEY=hf_your_access_key' >> .env.local
+```
+
+Different to other platforms, Hugging Face provides close to 50.000 models for various AI tasks, which enables you to
+easily try out different, specialized models for your use case. Common use cases can be found in this example directory.
+
+## Running the Examples
+
+You can run an example by executing the following command:
+
+```bash
+# Run all example with runner:
+./runner huggingface
+
+# Or run a specific example standalone, e.g., object detection:
+php huggingface/object-detection.php
+```
+
+## Available Models
+
+When running the examples, you might experience that some models are not available, and you encounter an error like:
+
+```
+Model, provider or task not found (404).
+```
+
+This can happen due to pre-selected models in the examples not being available anymore or not being "warmed up" on
+Hugging Face's side. You can change the model used in the examples by updating the model name in the example script.
+
+To find available models for a specific task, you can check out the [Hugging Face Model Hub](https://huggingface.co/models)
+and filter by the desired task, or you can use the `huggingface/_model-listing.php` script.
+
+### Listing Available Models
+
+List _all_ models:
+
+```bash
+php huggingface/_model-listing.php
+```
+(This is limited to 1000 results by default.)
+
+Limit models to a specific _task_, e.g., object-detection:
+
+```bash
+php huggingface/_model-listing.php --task=object-detection
+```
+
+Limit models to a specific _provider_, e.g., "hf-inference":
+
+```bash
+# Single provider:
+php huggingface/_model-listing.php --provider=hf-inference
+
+# Multiple providers:
+php huggingface/_model-listing.php --provider=sambanova,novita
+```
+
+Search for models matching a specific term, e.g., "gpt":
+
+```bash
+php huggingface/_model-listing.php --search=gpt
+```
+
+Limit models to currently warm models:
+
+```bash
+php huggingface/_model-listing.php --warm
+```
+
+You can combine task and provider filters, task and warm filters, but not provider and warm filters.
+
+```bash
+# Combine provider and task:
+php huggingface/_model-listing.php --provider=hf-inference --task=object-detection
+
+# Combine task and warm:
+php huggingface/_model-listing.php --task=object-detection --warm
+
+# Search for warm gpt model for text-generation:
+php huggingface/_model-listing.php --warm --task=text-generation --search=gpt
+```
+
+### Model Information
+
+To get detailed information about a specific model, you can use the `huggingface/_model-info.php` script:
+
+```bash
+php huggingface/_model-info.php google/vit-base-patch16-224
+
+Hugging Face Model Information
+==============================
+
+ Model: google/vit-base-patch16-224
+ ----------- -----------------------------
+  ID          google/vit-base-patch16-224
+  Downloads   2985836
+  Likes       889
+  Task        image-classification
+  Warm        yes
+ ----------- -----------------------------
+
+ Inference Provider:
+ ----------------- -----------------------------
+  Provider          hf-inference
+  Status            live
+  Provider ID       google/vit-base-patch16-224
+  Task              image-classification
+  Is Model Author   no
+ ----------------- -----------------------------
+```
+
+Important to understand is what you can use a model for and its availability on different providers.

examples/huggingface/_model-info.php

@@ -0,0 +1,64 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\AI\Platform\Bridge\HuggingFace\ApiClient;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\SingleCommandApplication;
+use Symfony\Component\Console\Style\SymfonyStyle;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+$app = (new SingleCommandApplication('Hugging Face Model Listing'))
+    ->setDescription('Inference information about a model on Hugging Face')
+    ->addArgument('model', InputArgument::REQUIRED, 'Name of the model to get information about')
+    ->setCode(function (InputInterface $input, OutputInterface $output) {
+        $io = new SymfonyStyle($input, $output);
+        $io->title('Hugging Face Model Information');
+
+        $model = $input->getArgument('model');
+        $info = (new ApiClient())->getModel($model);
+
+        $io->text(sprintf('Model: %s', $model));
+
+        $io->horizontalTable(
+            ['ID', 'Downloads', 'Likes', 'Task', 'Warm'],
+            [[
+                $info['id'],
+                $info['downloads'],
+                $info['likes'],
+                $info['pipeline_tag'],
+                ('warm' === ($info['inference'] ?? null)) ? 'yes' : 'no',
+            ]]
+        );
+
+        $io->text('Inference Provider:');
+        if (!isset($info['inferenceProviderMapping']) || [] === $info['inferenceProviderMapping']) {
+            $io->text('<comment>No inference provider information available for this model.</comment>');
+            $io->newLine();
+        } else {
+            $io->horizontalTable(
+                ['Provider', 'Status', 'Provider ID', 'Task', 'Is Model Author'],
+                array_map(fn (string $provider, array $data) => [
+                    $provider,
+                    $data['status'],
+                    $data['providerId'],
+                    $data['task'],
+                    $data['isModelAuthor'] ? 'yes' : 'no',
+                ], array_keys($info['inferenceProviderMapping']), $info['inferenceProviderMapping'])
+            );
+        }
+
+        return Command::SUCCESS;
+    })
+    ->run();

examples/huggingface/_model-listing.php

@@ -20,28 +20,36 @@
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
-$app = (new SingleCommandApplication('HuggingFace Model Listing'))
-    ->setDescription('Lists all available models on HuggingFace')
+$app = (new SingleCommandApplication('Hugging Face Model Listing'))
+    ->setDescription('Lists all available models on Hugging Face')
     ->addOption('provider', 'p', InputOption::VALUE_REQUIRED, 'Name of the inference provider to filter models by')
     ->addOption('task', 't', InputOption::VALUE_REQUIRED, 'Name of the task to filter models by')
+    ->addOption('warm', 'w', InputOption::VALUE_NONE, 'Only list models that are "warm" (i.e. ready for inference without cold start)')
+    ->addOption('search', 's', InputOption::VALUE_REQUIRED, 'Search term to filter models by')
     ->setCode(function (InputInterface $input, OutputInterface $output) {
         $io = new SymfonyStyle($input, $output);
-        $io->title('HuggingFace Model Listing');
+        $io->title('Hugging Face Model Listing');
 
         $provider = $input->getOption('provider');
         $task = $input->getOption('task');
+        $search = $input->getOption('search');
+        $warm = (bool) $input->getOption('warm');
 
-        $models = (new ApiClient())->models($provider, $task);
+        $models = (new ApiClient())->getModels($provider, $task, $search, $warm);
 
         if (0 === count($models)) {
-            $io->error('No models found for the given provider and task.');
+            $io->error('No models found for the given filters.');
 
             return Command::FAILURE;
         }
 
-        $io->listing(
-            array_map(fn (Model $model) => $model->getName(), $models)
-        );
+        $formatModel = function (Model $model) {
+            return sprintf('%s <comment>[%s]</>', $model->getName(), implode(', ', $model->getOptions()['tags'] ?? []));
+        };
+
+        $io->listing(array_map($formatModel, $models));
+
+        $io->success(sprintf('Found %d model(s).', count($models)));
 
         return Command::SUCCESS;
     })

examples/huggingface/object-detection.php

@@ -17,7 +17,7 @@
 
 $platform = PlatformFactory::create(env('HUGGINGFACE_KEY'), httpClient: http_client());
 
-$image = Image::fromFile(dirname(__DIR__, 2).'/fixtures/image.jpg');
+$image = Image::fromFile(dirname(__DIR__, 2).'/fixtures/accordion.jpg');
 $result = $platform->invoke('facebook/detr-resnet-50', $image, [
     'task' => Task::OBJECT_DETECTION,
 ]);

examples/huggingface/table-question-answering.php

@@ -19,12 +19,12 @@
 $input = [
     'query' => 'select year where city = beijing',
     'table' => [
-        'year' => [1896, 1900, 1904, 2004, 2008, 2012],
+        'year' => ['1896', '1900', '1904', '2004', '2008', '2012'],
         'city' => ['athens', 'paris', 'st. louis', 'athens', 'beijing', 'london'],
     ],
 ];
 
-$result = $platform->invoke('microsoft/tapex-base', $input, [
+$result = $platform->invoke('google/tapas-base-finetuned-wtq', $input, [
     'task' => Task::TABLE_QUESTION_ANSWERING,
 ]);
 

examples/huggingface/text-generation.php

@@ -16,7 +16,7 @@
 
 $platform = PlatformFactory::create(env('HUGGINGFACE_KEY'), httpClient: http_client());
 
-$result = $platform->invoke('gpt2', 'The quick brown fox jumps over the lazy', [
+$result = $platform->invoke('katanemo/Arch-Router-1.5B', 'The quick brown fox jumps over the lazy', [
     'task' => Task::TEXT_GENERATION,
 ]);
 

fixtures/README.md

@@ -0,0 +1,8 @@
+# Fixture Licenses
+
+For testing multi-modal features, the repository contains binary media content, with the following owners and licenses:
+
+* `tests/Fixture/accordion.jpg`: Jefferson Lucena, Creative Commons, see [pexels.com](https://www.pexels.com/photo/man-playing-accordion-10153219/)
+* `tests/Fixture/audio.mp3`: davidbain, Creative Commons, see [freesound.org](https://freesound.org/people/davidbain/sounds/136777/)
+* `tests/Fixture/document.pdf`: Chem8240ja, Public Domain, see [Wikipedia](https://en.m.wikipedia.org/wiki/File:Re_example.pdf)
+* `tests/Fixture/image.jpg`: Chris F., Creative Commons, see [pexels.com](https://www.pexels.com/photo/blauer-und-gruner-elefant-mit-licht-1680755/)

fixtures/accordion.jpg

@@ -11,6 +11,7 @@
 
 namespace Symfony\AI\Platform\Bridge\HuggingFace;
 
+use Symfony\AI\Platform\Exception\RuntimeException;
 use Symfony\AI\Platform\Model;
 use Symfony\Component\HttpClient\HttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -27,17 +28,78 @@ public function __construct(
     }
 
     /**
+     * @return array{
+     *     id: string,
+     *     downloads: int,
+     *     likes: int,
+     *     pipeline_tag: string|null,
+     *     inference: string|null,
+     *     inferenceProviderMapping: array<string, array{
+     *         status: 'live'|'staging',
+     *         providerId: string,
+     *         task: string,
+     *         isModelAuthor: bool,
+     *     }>|null,
+     * }
+     */
+    public function getModel(string $modelId): array
+    {
+        $result = $this->httpClient->request('GET', 'https://huggingface.co/api/models/'.$modelId, [
+            'query' => [
+                'expand' => ['downloads', 'likes', 'pipeline_tag', 'inference', 'inferenceProviderMapping'],
+            ],
+        ]);
+
+        $data = $result->toArray(false);
+
+        if (isset($data['error'])) {
+            throw new RuntimeException(\sprintf('Error fetching model info for "%s": "%s"', $modelId, $data['error']));
+        }
+
+        return $data;
+    }
+
+    /**
+     * @param ?string $provider Filter by inference provider (see Provider::*)
+     * @param ?string $task     Filter by task (see Task::*)
+     * @param ?string $search   Search term to filter models by
+     * @param bool    $warm     Filter for models with warm inference available
+     *
      * @return Model[]
      */
-    public function models(?string $provider, ?string $task): array
+    public function getModels(?string $provider = null, ?string $task = null, ?string $search = null, bool $warm = false): array
     {
         $result = $this->httpClient->request('GET', 'https://huggingface.co/api/models', [
             'query' => [
                 'inference_provider' => $provider,
                 'pipeline_tag' => $task,
+                'search' => $search,
+                ...$warm ? ['inference' => 'warm'] : [],
             ],
         ]);
 
-        return array_map(fn (array $model) => new Model($model['id']), $result->toArray());
+        $data = $result->toArray(false);
+
+        if (isset($data['error'])) {
+            throw new RuntimeException(\sprintf('Error fetching models: "%s"', $data['error']));
+        }
+
+        return array_map($this->convertToModel(...), $data);
+    }
+
+    /**
+     * @param array{
+     *     id: string,
+     *     pipeline_tag?: string,
+     * } $data
+     */
+    private function convertToModel(array $data): Model
+    {
+        return new Model(
+            $data['id'],
+            options: [
+                'tags' => isset($data['pipeline_tag']) ? [$data['pipeline_tag']] : [],
+            ],
+        );
     }
 }