materio_ai: Ollama embedding client with timeout, num_thread and dimension check (V2)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ShDspHaZGwHoRZCsPBJzsM
This commit is contained in:
2026-11-16 19:46:22 +01:00
co-authored by Claude Opus 5.5
parent 890c80eb12
commit 45f21b2e49
4 changed files with 175 additions and 0 deletions
@@ -2,3 +2,8 @@ services:
logger.channel.materio_ai:
parent: logger.channel_base
arguments: ['materio_ai']
materio_ai.embedding_client:
class: Drupal\materio_ai\Embedding\OllamaEmbeddingClient
arguments: ['@http_client', '@config.factory']
Drupal\materio_ai\Embedding\EmbeddingClientInterface: '@materio_ai.embedding_client'
@@ -0,0 +1,48 @@
<?php
declare(strict_types=1);
namespace Drupal\materio_ai\Embedding;
/**
* Turns texts into vectors with the embedding model.
*/
interface EmbeddingClientInterface {
/**
* Returns the vector of one text.
*
* @return float[]
* A vector of getDimension() values.
*
* @throws \Drupal\materio_ai\Exception\EmbeddingException
*/
public function embed(string $text): array;
/**
* Returns the vectors of several texts, in the same order and with the same keys.
*
* Texts are sent one per call: Ollama gains nothing from batches on CPU
* (measured in M2).
*
* @param string[] $texts
* The texts to vectorize.
*
* @return float[][]
* The vectors, keyed like $texts.
*
* @throws \Drupal\materio_ai\Exception\EmbeddingException
*/
public function embedMultiple(array $texts): array;
/**
* Returns the model name, stored with each vector.
*/
public function getModel(): string;
/**
* Returns the expected vector dimension.
*/
public function getDimension(): int;
}
@@ -0,0 +1,107 @@
<?php
declare(strict_types=1);
namespace Drupal\materio_ai\Embedding;
use Drupal\Core\Config\ConfigFactoryInterface;
use Drupal\Core\Config\ImmutableConfig;
use Drupal\materio_ai\Exception\EmbeddingException;
use GuzzleHttp\ClientInterface;
use GuzzleHttp\Exception\GuzzleException;
/**
* Embedding client for an Ollama service (POST /api/embed).
*/
final class OllamaEmbeddingClient implements EmbeddingClientInterface {
public function __construct(
private readonly ClientInterface $httpClient,
private readonly ConfigFactoryInterface $configFactory,
) {}
/**
* {@inheritdoc}
*/
public function embed(string $text): array {
$text = trim($text);
if ($text === '') {
throw new EmbeddingException('Cannot vectorize an empty text.');
}
$config = $this->config();
$timeout = max(1, (int) $config->get('timeout'));
$url = rtrim((string) $config->get('url'), '/') . '/api/embed';
try {
$response = $this->httpClient->request('POST', $url, [
'json' => [
'model' => $this->getModel(),
'input' => $text,
// Ollama counts the cores of the host, not the CPU limit of its
// container: without this option it starts too many threads.
'options' => ['num_thread' => max(1, (int) $config->get('num_thread'))],
],
'timeout' => $timeout,
'connect_timeout' => min($timeout, 3),
]);
}
catch (GuzzleException $e) {
throw new EmbeddingException(sprintf('Embedding service %s failed: %s', $url, $e->getMessage()), 0, $e);
}
try {
$data = json_decode((string) $response->getBody(), TRUE, 512, JSON_THROW_ON_ERROR);
}
catch (\JsonException $e) {
throw new EmbeddingException(sprintf('Embedding service %s returned invalid JSON.', $url), 0, $e);
}
$vector = $data['embeddings'][0] ?? NULL;
if (!is_array($vector)) {
throw new EmbeddingException(sprintf('Embedding service %s returned no vector.', $url));
}
$dimension = $this->getDimension();
if (count($vector) !== $dimension) {
throw new EmbeddingException(sprintf('Expected a vector of %d values, got %d (model %s).', $dimension, count($vector), $this->getModel()));
}
foreach ($vector as $value) {
if (!is_int($value) && !is_float($value)) {
throw new EmbeddingException('The vector contains a non numeric value.');
}
}
return array_map('floatval', $vector);
}
/**
* {@inheritdoc}
*/
public function embedMultiple(array $texts): array {
$vectors = [];
foreach ($texts as $key => $text) {
$vectors[$key] = $this->embed($text);
}
return $vectors;
}
/**
* {@inheritdoc}
*/
public function getModel(): string {
return (string) $this->config()->get('model');
}
/**
* {@inheritdoc}
*/
public function getDimension(): int {
return (int) $this->config()->get('dimension');
}
/**
* Returns the module settings.
*/
private function config(): ImmutableConfig {
return $this->configFactory->get('materio_ai.settings');
}
}
@@ -0,0 +1,15 @@
<?php
declare(strict_types=1);
namespace Drupal\materio_ai\Exception;
/**
* The embedding service could not return a valid vector.
*
* Covers an unreachable or stopped service, a timeout, an HTTP error, an
* unexpected response and a vector of the wrong dimension.
*/
class EmbeddingException extends \RuntimeException {
}