1 Commits
Author SHA1 Message Date
bachirandClaude Opus 5.5 6d8c64c94f materio_ai: cached search vectors, 1 s delay, pause and cron warm-up (H8)
- QueryEmbedder: vector of a search phrase cached 30 days (cache bin
  materio_ai), model given search_timeout seconds (1 by default, new
  setting, update 11001), left alone 60 s after a failure
  (ModelPausedException, not logged).
- NeighbourSearch honours the enabled setting: the search called the model
  even when materio_ai was switched off.
- materio_ai_cron() loads the model with the normal timeout: after a
  restart, loading (2.9 s) exceeds the search delay and Ollama drops it,
  so searches alone would never load it. Ultimate cron job exported.
- On any model failure the search answers with the keyword results only.
- QueryEmbedderTest: cache, delay, pause, cache during the pause, warm-up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ShDspHaZGwHoRZCsPBJzsM
2026-11-17 18:26:19 +01:00
15 changed files with 379 additions and 13 deletions
+1
View File
@@ -5,4 +5,5 @@ url: 'http://ollama:11434'
model: 'bge-m3:567m'
dimension: 1024
timeout: 10
search_timeout: 1.0
num_thread: 4
@@ -0,0 +1,17 @@
uuid: 77f99dd9-eeab-40af-9925-95a9f7cd6cee
langcode: en
status: true
dependencies:
module:
- materio_ai
title: 'Default cron handler'
id: materio_ai_cron
weight: 0
module: materio_ai
callback: 'materio_ai#cron'
scheduler:
id: simple
launcher:
id: serial
logger:
id: database
@@ -7,6 +7,9 @@ model: 'bge-m3:567m'
dimension: 1024
# Délai maximal d'un appel au modèle, en secondes.
timeout: 10
# Délai maximal du calcul du vecteur d'une recherche, en secondes : au-delà, la
# recherche répond avec les seuls mots-clés (H8).
search_timeout: 1.0
# Threads de calcul envoyés à chaque appel (options.num_thread) : Ollama ne voit pas
# la limite de CPU du conteneur, sans ce réglage il lance trop de threads (mesure M2).
num_thread: 4
@@ -17,6 +17,9 @@ materio_ai.settings:
timeout:
type: integer
label: 'Timeout (seconds)'
search_timeout:
type: float
label: 'Search timeout (seconds)'
num_thread:
type: integer
label: 'Threads per call'
@@ -58,3 +58,13 @@ function materio_ai_schema(): array {
];
return $schema;
}
/**
* Adds the search timeout setting (H8).
*/
function materio_ai_update_11001(): void {
$config = \Drupal::configFactory()->getEditable('materio_ai.settings');
if ($config->get('search_timeout') === NULL) {
$config->set('search_timeout', 1.0)->save(TRUE);
}
}
@@ -7,6 +7,7 @@
declare(strict_types=1);
use Drupal\materio_ai\Exception\EmbeddingException;
use Drupal\node\NodeInterface;
use Drupal\taxonomy\TermInterface;
@@ -66,3 +67,22 @@ function materio_ai_taxonomy_term_translation_delete(TermInterface $translation)
function materio_ai_taxonomy_term_predelete(TermInterface $term): void {
\Drupal::service('materio_ai.vectorizer')->enqueueForTerm($term, TRUE);
}
/**
* Implements hook_cron().
*
* Loads the model: a search gives it 1 s, too short to load it after a
* restart of Ollama (H8).
*/
function materio_ai_cron(): void {
$embedder = \Drupal::service('materio_ai.query_embedder');
if (!$embedder->isEnabled()) {
return;
}
try {
$embedder->warmUp();
}
catch (EmbeddingException $e) {
\Drupal::logger('materio_ai')->warning('Model warm-up failed: @message', ['@message' => $e->getMessage()]);
}
}
@@ -35,9 +35,21 @@ services:
tags:
- { name: event_subscriber }
cache.materio_ai:
class: Drupal\Core\Cache\CacheBackendInterface
tags:
- { name: cache.bin }
factory: ['@cache_factory', 'get']
arguments: [materio_ai]
materio_ai.query_embedder:
class: Drupal\materio_ai\Search\QueryEmbedder
arguments: ['@materio_ai.embedding_client', '@cache.materio_ai', '@config.factory', '@datetime.time']
Drupal\materio_ai\Search\QueryEmbedder: '@materio_ai.query_embedder'
materio_ai.neighbour_search:
class: Drupal\materio_ai\Search\NeighbourSearch
arguments: ['@entity_type.manager', '@language_manager', '@config.factory', '@materio_ai.embedding_client']
arguments: ['@entity_type.manager', '@language_manager', '@config.factory', '@materio_ai.query_embedder']
Drupal\materio_ai\Search\NeighbourSearch: '@materio_ai.neighbour_search'
materio_ai.knn_query_subscriber:
@@ -12,12 +12,18 @@ interface EmbeddingClientInterface {
/**
* Returns the vector of one text.
*
* @param string $text
* The text to vectorize.
* @param float|null $timeout
* Longest wait in seconds; the configured timeout by default. A search
* passes a short one (search_timeout, H8).
*
* @return float[]
* A vector of getDimension() values.
*
* @throws \Drupal\materio_ai\Exception\EmbeddingException
*/
public function embed(string $text): array;
public function embed(string $text, ?float $timeout = NULL): array;
/**
* Returns the vectors of several texts, in the same order and with the same keys.
@@ -23,13 +23,13 @@ final class OllamaEmbeddingClient implements EmbeddingClientInterface {
/**
* {@inheritdoc}
*/
public function embed(string $text): array {
public function embed(string $text, ?float $timeout = NULL): array {
$text = trim($text);
if ($text === '') {
throw new EmbeddingException('Cannot vectorize an empty text.');
}
$config = $this->config();
$timeout = max(1, (int) $config->get('timeout'));
$timeout ??= (float) max(1, (int) $config->get('timeout'));
$url = rtrim((string) $config->get('url'), '/') . '/api/embed';
try {
@@ -42,7 +42,7 @@ final class OllamaEmbeddingClient implements EmbeddingClientInterface {
'options' => ['num_thread' => max(1, (int) $config->get('num_thread'))],
],
'timeout' => $timeout,
'connect_timeout' => min($timeout, 3),
'connect_timeout' => min($timeout, 3.0),
]);
}
catch (GuzzleException $e) {
@@ -0,0 +1,12 @@
<?php
declare(strict_types=1);
namespace Drupal\materio_ai\Exception;
/**
* The model is not called: it failed less than QueryEmbedder::PAUSE seconds ago.
*
* The failure itself was already logged; this one is not worth a log line.
*/
final class ModelPausedException extends EmbeddingException {}
@@ -63,6 +63,15 @@ final class SettingsForm extends ConfigFormBase {
'#required' => TRUE,
'#config_target' => 'materio_ai.settings:timeout',
];
$form['search_timeout'] = [
'#type' => 'number',
'#title' => $this->t('Search timeout (seconds)'),
'#description' => $this->t('Longest wait for the vector of a search. Past it, the search answers with keywords only.'),
'#min' => 0.1,
'#step' => 0.1,
'#required' => TRUE,
'#config_target' => 'materio_ai.settings:search_timeout',
];
$form['num_thread'] = [
'#type' => 'number',
'#title' => $this->t('Threads per call'),
@@ -7,7 +7,6 @@ namespace Drupal\materio_ai\Search;
use Drupal\Core\Config\ConfigFactoryInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Language\LanguageManagerInterface;
use Drupal\materio_ai\Embedding\EmbeddingClientInterface;
use Drupal\search_api\Utility\Utility;
/**
@@ -41,7 +40,7 @@ final class NeighbourSearch {
private readonly EntityTypeManagerInterface $entityTypeManager,
private readonly LanguageManagerInterface $languageManager,
private readonly ConfigFactoryInterface $configFactory,
private readonly EmbeddingClientInterface $client,
private readonly QueryEmbedder $embedder,
) {}
/**
@@ -55,16 +54,21 @@ final class NeighbourSearch {
* Number of neighbours (topK).
*
* @return array<int, float>
* Scores keyed by nid, best first. Solr score of a cosine kNN query:
* Scores keyed by nid, best first, none when materio_ai is switched off.
* Solr score of a cosine kNN query:
* (1 + cosine) / 2.
*
* @throws \Drupal\materio_ai\Exception\EmbeddingException
* When the model fails.
* When the model fails or is too slow (QueryEmbedder).
* @throws \Drupal\search_api\SearchApiException
* When Solr fails.
*/
public function search(string $phrase, ?string $langcode = NULL, int $limit = 100): array {
return $this->searchVector($this->client->embed($phrase), $langcode, $limit);
// Switched off: no text is sent to the model, keyword results only.
if (!$this->embedder->isEnabled()) {
return [];
}
return $this->searchVector($this->embedder->embed($phrase), $langcode, $limit);
}
/**
@@ -0,0 +1,105 @@
<?php
declare(strict_types=1);
namespace Drupal\materio_ai\Search;
use Drupal\Component\Datetime\TimeInterface;
use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Config\ConfigFactoryInterface;
use Drupal\materio_ai\Embedding\EmbeddingClientInterface;
use Drupal\materio_ai\Exception\EmbeddingException;
use Drupal\materio_ai\Exception\ModelPausedException;
/**
* Vector of a search phrase: cached, with a short delay and a pause (H8).
*
* A search must answer even when the model is slow or stopped:
* - vectors are cached by model and phrase (cache bin materio_ai, Redis on
* the servers); they hold nothing about the user, so one entry serves
* everybody;
* - the model gets search_timeout seconds (1 by default);
* - after a failure the model is left alone for PAUSE seconds: the searches
* of that time do not each wait for the delay again.
*
* On failure an EmbeddingException is thrown, and the caller answers with
* the keyword results.
*
* A model that took longer than the delay to load is unloaded again by
* Ollama when the call is dropped: searches alone would never load it after
* a restart (2.9 s measured locally). warmUp(), run by cron with the normal
* timeout, loads it.
*/
final class QueryEmbedder {
/**
* Lifetime of a cached vector, in seconds (30 days).
*/
public const LIFETIME = 2592000;
/**
* Seconds without calling the model after a failure.
*/
public const PAUSE = 60;
public function __construct(
private readonly EmbeddingClientInterface $client,
private readonly CacheBackendInterface $cache,
private readonly ConfigFactoryInterface $configFactory,
private readonly TimeInterface $time,
) {}
/**
* Whether the model may be called (setting « enabled »).
*/
public function isEnabled(): bool {
return (bool) $this->configFactory->get('materio_ai.settings')->get('enabled');
}
/**
* Loads the model with the normal timeout, and ends the pause.
*
* Uses the client options of the searches (num_thread): with other options
* Ollama would load the model again.
*
* @throws \Drupal\materio_ai\Exception\EmbeddingException
* When the model fails.
*/
public function warmUp(): void {
$this->client->embed('materiO');
$this->cache->delete('pause:' . $this->client->getModel());
}
/**
* Returns the vector of a phrase.
*
* @return float[]
* The vector.
*
* @throws \Drupal\materio_ai\Exception\EmbeddingException
* When the model fails or is too slow; ModelPausedException when it
* failed less than PAUSE seconds ago.
*/
public function embed(string $phrase): array {
$model = $this->client->getModel();
$cid = 'query:' . $model . ':' . hash('sha256', $phrase);
if ($cached = $this->cache->get($cid)) {
return $cached->data;
}
$pause_cid = 'pause:' . $model;
if ($this->cache->get($pause_cid)) {
throw new ModelPausedException(sprintf('Model %s paused after a failure.', $model));
}
$timeout = (float) ($this->configFactory->get('materio_ai.settings')->get('search_timeout') ?? 1.0);
try {
$vector = $this->client->embed($phrase, max(0.1, $timeout));
}
catch (EmbeddingException $e) {
$this->cache->set($pause_cid, TRUE, $this->time->getRequestTime() + self::PAUSE);
throw $e;
}
$this->cache->set($cid, $vector, $this->time->getRequestTime() + self::LIFETIME);
return $vector;
}
}
@@ -0,0 +1,159 @@
<?php
declare(strict_types=1);
namespace Drupal\Tests\materio_ai\Unit;
use Drupal\Component\Datetime\TimeInterface;
use Drupal\Core\Cache\MemoryBackend;
use Drupal\materio_ai\Embedding\EmbeddingClientInterface;
use Drupal\materio_ai\Exception\EmbeddingException;
use Drupal\materio_ai\Exception\ModelPausedException;
use Drupal\materio_ai\Search\QueryEmbedder;
use Drupal\Tests\UnitTestCase;
use PHPUnit\Framework\Attributes\CoversClass;
use PHPUnit\Framework\Attributes\Group;
/**
* Tests the cache, delay and pause of the search vectors (H8).
*/
#[CoversClass(QueryEmbedder::class)]
#[Group('materio_ai')]
final class QueryEmbedderTest extends UnitTestCase {
/**
* Fake model: counts the calls, fails on demand, records the timeouts.
*/
private object $client;
/**
* Request time, moved forward by the tests.
*/
private int $now = 1_000_000;
private MemoryBackend $cache;
private QueryEmbedder $embedder;
/**
* {@inheritdoc}
*/
protected function setUp(): void {
parent::setUp();
$this->client = new class implements EmbeddingClientInterface {
public int $calls = 0;
public bool $fail = FALSE;
/**
* @var array<float|null>
*/
public array $timeouts = [];
public function embed(string $text, ?float $timeout = NULL): array {
$this->calls++;
$this->timeouts[] = $timeout;
if ($this->fail) {
throw new EmbeddingException('cURL error 28: Operation timed out');
}
return [(float) strlen($text), 1.0];
}
public function embedMultiple(array $texts): array {
return array_map($this->embed(...), $texts);
}
public function getModel(): string {
return 'bge-m3:567m';
}
public function getDimension(): int {
return 2;
}
};
$time = $this->createStub(TimeInterface::class);
$time->method('getRequestTime')->willReturnCallback(fn () => $this->now);
$time->method('getCurrentTime')->willReturnCallback(fn () => $this->now);
$this->cache = new MemoryBackend($time);
$config = $this->getConfigFactoryStub(['materio_ai.settings' => ['enabled' => TRUE, 'search_timeout' => 1.0]]);
$this->embedder = new QueryEmbedder($this->client, $this->cache, $config, $time);
}
/**
* The second search of a phrase does not call the model.
*/
public function testCachedVector(): void {
$first = $this->embedder->embed('bois brûlé');
$this->assertSame($first, $this->embedder->embed('bois brûlé'));
$this->assertSame(1, $this->client->calls);
$this->embedder->embed('bois flotté');
$this->assertSame(2, $this->client->calls);
}
/**
* A search gives the model search_timeout seconds, not the normal timeout.
*/
public function testSearchTimeout(): void {
$this->embedder->embed('bois');
$this->assertSame([1.0], $this->client->timeouts);
}
/**
* After a failure the model is not called for PAUSE seconds.
*/
public function testPauseAfterFailure(): void {
$this->client->fail = TRUE;
try {
$this->embedder->embed('bois');
$this->fail('The failure is passed on.');
}
catch (EmbeddingException $e) {
$this->assertNotInstanceOf(ModelPausedException::class, $e);
}
$this->client->fail = FALSE;
$this->now += QueryEmbedder::PAUSE - 1;
try {
$this->embedder->embed('verre');
$this->fail('The model is paused.');
}
catch (ModelPausedException) {
}
$this->assertSame(1, $this->client->calls);
$this->now += 2;
$this->assertNotEmpty($this->embedder->embed('verre'));
$this->assertSame(2, $this->client->calls);
}
/**
* A cached vector is served even during the pause.
*/
public function testCacheDuringPause(): void {
$vector = $this->embedder->embed('bois');
$this->client->fail = TRUE;
try {
$this->embedder->embed('verre');
}
catch (EmbeddingException) {
}
$this->assertSame($vector, $this->embedder->embed('bois'));
}
/**
* The cron warm-up uses the normal timeout and ends the pause.
*/
public function testWarmUpEndsPause(): void {
$this->client->fail = TRUE;
try {
$this->embedder->embed('bois');
}
catch (EmbeddingException) {
}
$this->client->fail = FALSE;
$this->embedder->warmUp();
$this->assertNull(end($this->client->timeouts));
$this->assertNotEmpty($this->embedder->embed('bois'));
}
}
@@ -7,6 +7,7 @@ use Drupal\Core\Controller\ControllerBase;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Drupal\Component\Utility\Unicode;
use Drupal\materio_ai\Exception\ModelPausedException;
use Drupal\materio_sapi\KeywordText;
use Drupal\materio_sapi\RankFusion;
use Drupal\search_api\Entity\Index;
@@ -165,8 +166,9 @@ class Base extends ControllerBase {
* Nodes closest in meaning to the phrase (materio_ai, Solr kNN).
*
* Not for a term chosen in the autocomplete (direct search) nor without
* the materio_ai service. On a model or Solr error, the keyword results
* stand alone (delay and cache in H8).
* the materio_ai service. On a model or Solr error, or past the delay of
* QueryEmbedder (1 s), the keyword results stand alone, with no message:
* the search answers as before H5.
*
* @return array<int, float>
* Scores keyed by nid, best first.
@@ -184,7 +186,10 @@ class Base extends ControllerBase {
return \Drupal::service('materio_ai.neighbour_search')->search($phrase, $lang, self::KNN_LIMIT);
}
catch (\Throwable $e) {
// Paused model: its failure was logged when it happened.
if (!$e instanceof ModelPausedException) {
\Drupal::logger('materio_sapi')->warning('Neighbour search failed, keyword results only: @message', ['@message' => $e->getMessage()]);
}
return [];
}
}