From 6d8c64c94fb854d46801a1aaf448ab6f8a37c9a7 Mon Sep 17 00:00:00 2001 From: bach Date: Tue, 17 Nov 2026 18:26:19 +0100 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01ShDspHaZGwHoRZCsPBJzsM --- config/sync/materio_ai.settings.yml | 1 + .../ultimate_cron.job.materio_ai_cron.yml | 17 ++ .../config/install/materio_ai.settings.yml | 3 + .../config/schema/materio_ai.schema.yml | 3 + .../custom/materio_ai/materio_ai.install | 10 ++ .../custom/materio_ai/materio_ai.module | 20 +++ .../custom/materio_ai/materio_ai.services.yml | 14 +- .../Embedding/EmbeddingClientInterface.php | 8 +- .../src/Embedding/OllamaEmbeddingClient.php | 6 +- .../src/Exception/ModelPausedException.php | 12 ++ .../materio_ai/src/Form/SettingsForm.php | 9 + .../materio_ai/src/Search/NeighbourSearch.php | 14 +- .../materio_ai/src/Search/QueryEmbedder.php | 105 ++++++++++++ .../tests/src/Unit/QueryEmbedderTest.php | 159 ++++++++++++++++++ .../materio_sapi/src/Controller/Base.php | 11 +- 15 files changed, 379 insertions(+), 13 deletions(-) create mode 100644 config/sync/ultimate_cron.job.materio_ai_cron.yml create mode 100644 web/modules/custom/materio_ai/src/Exception/ModelPausedException.php create mode 100644 web/modules/custom/materio_ai/src/Search/QueryEmbedder.php create mode 100644 web/modules/custom/materio_ai/tests/src/Unit/QueryEmbedderTest.php diff --git a/config/sync/materio_ai.settings.yml b/config/sync/materio_ai.settings.yml index 03e79a42..75a734da 100644 --- a/config/sync/materio_ai.settings.yml +++ b/config/sync/materio_ai.settings.yml @@ -5,4 +5,5 @@ url: 'http://ollama:11434' model: 'bge-m3:567m' dimension: 1024 timeout: 10 +search_timeout: 1.0 num_thread: 4 diff --git a/config/sync/ultimate_cron.job.materio_ai_cron.yml b/config/sync/ultimate_cron.job.materio_ai_cron.yml new file mode 100644 index 00000000..eeef0b18 --- /dev/null +++ b/config/sync/ultimate_cron.job.materio_ai_cron.yml @@ -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 diff --git a/web/modules/custom/materio_ai/config/install/materio_ai.settings.yml b/web/modules/custom/materio_ai/config/install/materio_ai.settings.yml index b4dd5e0d..4702f413 100644 --- a/web/modules/custom/materio_ai/config/install/materio_ai.settings.yml +++ b/web/modules/custom/materio_ai/config/install/materio_ai.settings.yml @@ -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 diff --git a/web/modules/custom/materio_ai/config/schema/materio_ai.schema.yml b/web/modules/custom/materio_ai/config/schema/materio_ai.schema.yml index 29735f07..1a46c946 100644 --- a/web/modules/custom/materio_ai/config/schema/materio_ai.schema.yml +++ b/web/modules/custom/materio_ai/config/schema/materio_ai.schema.yml @@ -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' diff --git a/web/modules/custom/materio_ai/materio_ai.install b/web/modules/custom/materio_ai/materio_ai.install index 51fc6b0f..9ad78ee1 100644 --- a/web/modules/custom/materio_ai/materio_ai.install +++ b/web/modules/custom/materio_ai/materio_ai.install @@ -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); + } +} diff --git a/web/modules/custom/materio_ai/materio_ai.module b/web/modules/custom/materio_ai/materio_ai.module index bb60484a..e6ec7395 100644 --- a/web/modules/custom/materio_ai/materio_ai.module +++ b/web/modules/custom/materio_ai/materio_ai.module @@ -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()]); + } +} diff --git a/web/modules/custom/materio_ai/materio_ai.services.yml b/web/modules/custom/materio_ai/materio_ai.services.yml index 8f538fb9..1787d7fc 100644 --- a/web/modules/custom/materio_ai/materio_ai.services.yml +++ b/web/modules/custom/materio_ai/materio_ai.services.yml @@ -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: diff --git a/web/modules/custom/materio_ai/src/Embedding/EmbeddingClientInterface.php b/web/modules/custom/materio_ai/src/Embedding/EmbeddingClientInterface.php index 16f04e95..51d72093 100644 --- a/web/modules/custom/materio_ai/src/Embedding/EmbeddingClientInterface.php +++ b/web/modules/custom/materio_ai/src/Embedding/EmbeddingClientInterface.php @@ -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. diff --git a/web/modules/custom/materio_ai/src/Embedding/OllamaEmbeddingClient.php b/web/modules/custom/materio_ai/src/Embedding/OllamaEmbeddingClient.php index cc3c9d45..428e09bc 100644 --- a/web/modules/custom/materio_ai/src/Embedding/OllamaEmbeddingClient.php +++ b/web/modules/custom/materio_ai/src/Embedding/OllamaEmbeddingClient.php @@ -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) { diff --git a/web/modules/custom/materio_ai/src/Exception/ModelPausedException.php b/web/modules/custom/materio_ai/src/Exception/ModelPausedException.php new file mode 100644 index 00000000..7a634161 --- /dev/null +++ b/web/modules/custom/materio_ai/src/Exception/ModelPausedException.php @@ -0,0 +1,12 @@ + 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'), diff --git a/web/modules/custom/materio_ai/src/Search/NeighbourSearch.php b/web/modules/custom/materio_ai/src/Search/NeighbourSearch.php index ad2fe4f7..15c106c6 100644 --- a/web/modules/custom/materio_ai/src/Search/NeighbourSearch.php +++ b/web/modules/custom/materio_ai/src/Search/NeighbourSearch.php @@ -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 - * 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); } /** diff --git a/web/modules/custom/materio_ai/src/Search/QueryEmbedder.php b/web/modules/custom/materio_ai/src/Search/QueryEmbedder.php new file mode 100644 index 00000000..1dea83d1 --- /dev/null +++ b/web/modules/custom/materio_ai/src/Search/QueryEmbedder.php @@ -0,0 +1,105 @@ +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; + } + +} diff --git a/web/modules/custom/materio_ai/tests/src/Unit/QueryEmbedderTest.php b/web/modules/custom/materio_ai/tests/src/Unit/QueryEmbedderTest.php new file mode 100644 index 00000000..d91db516 --- /dev/null +++ b/web/modules/custom/materio_ai/tests/src/Unit/QueryEmbedderTest.php @@ -0,0 +1,159 @@ +client = new class implements EmbeddingClientInterface { + + public int $calls = 0; + + public bool $fail = FALSE; + + /** + * @var array + */ + 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')); + } + +} diff --git a/web/modules/custom/materio_sapi/src/Controller/Base.php b/web/modules/custom/materio_sapi/src/Controller/Base.php index 151157b7..1cec78ce 100644 --- a/web/modules/custom/materio_sapi/src/Controller/Base.php +++ b/web/modules/custom/materio_sapi/src/Controller/Base.php @@ -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 * 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) { - \Drupal::logger('materio_sapi')->warning('Neighbour search failed, keyword results only: @message', ['@message' => $e->getMessage()]); + // 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 []; } }