hermes-memory-pgvector v0.5.3: Traga o Seu Próprio Modelo de Embedding

hermes-memory-pgvector é o plugin open-source que dá a uma frota de agentes hermes-agent memória partilhada e duradoura em PostgreSQL e pgvector. A versão 0.5.3 está disponível no PyPI e remove a última suposição codificada no plugin: que modelo de embedding transforma as suas memórias em vetores pesquisáveis.

Porque é que esta versão existe

Até agora, o modelo de embedding estava efetivamente fixo. O plugin verificava cada vetor contra umas literais 768 dimensões, o tamanho do modelo predefinido nomic-embed-text, e não tinha forma de enviar uma chave de API, pelo que serviços de embedding alojados estavam fora de alcance.

Isso tornou-se uma limitação real para a nossa própria implementação. Mudámos a base de dados de memória para text-embedding-3-small da OpenAI, servido através do OpenRouter, porque um endpoint alojado está sempre pronto, enquanto um modelo autoalojado pode demorar vários segundos a arrancar. As colunas da base de dados mudaram para 1536 dimensões, e o plugin não tinha nenhuma definição que as pudesse acompanhar. A v0.5.3 adiciona essas definições.

Três novas definições

• embed_dim é o comprimento do vetor que o seu modelo devolve. O valor predefinido é 768, por isso as configurações existentes não são afetadas. Cada embedding continua a ser verificada, agora com base neste valor, pelo que uma incompatibilidade falha rapidamente em vez de chegar à base de dados.
• embed_api_key_env é o nome de uma variável de ambiente que contém um token bearer, como OPENROUTER_API_KEY. A chave nunca vai no ficheiro de configuração; é lida no momento da chamada e nunca é registada.
• embed_protocol é openai, ollama ou auto. O valor predefinido, auto, tenta o caminho compatível com OpenAI e depois recorre à API nativa da Ollama. Escolher openai para um serviço alojado significa que um erro de autenticação ou de modelo é apresentado tal como é, em vez de ficar escondido atrás de um 404 vindo do fallback.

Apontar o plugin para text-embedding-3-small através do OpenRouter fica agora assim:

plugins:
  pgvector:
    embed_url: "https://openrouter.ai/api"
    embed_model: "openai/text-embedding-3-small"
    embed_dim: 1536
    embed_api_key_env: "OPENROUTER_API_KEY"
    embed_protocol: "openai"

Duas correções que fazem diferença mesmo que não mude nada

• Embeddings sob o carregador do plugin hermes-agent. Depois de carregar o plugin, o carregador do anfitrião volta a anexar todos os submódulos ao pacote, incluindo um chamado embed. Isso substituía a função que o plugin chamava, pelo que a incorporação falhava com TypeError: 'module' object is not callable e as gravações de memória eram descartadas em vez de serem armazenadas como texto. O plugin agora chama um alias privado que o carregador nunca toca.
• Endpoints lentos. Um servidor que aceitava a ligação mas respondia depois do timeout lançava um TimeoutError simples, que passava pela gestão de erros do plugin: sem fallback, sem tentativas e com uma gravação perdida. Agora é tratado como todas as outras falhas de endpoint.

Atualização

Os valores predefinidos não mudaram: 768 dimensões, sem cabeçalho de autenticação, o protocolo auto e sem novas migrações da base de dados. Atualize com:

pip install -U hermes-memory-pgvector

Mudar para um modelo com um tamanho de vetor diferente é uma migração da base de dados, não apenas uma edição da configuração, porque vetores de dois modelos diferentes não são comparáveis. O README explica como fazer: altere o tipo da coluna, re-embeda as linhas existentes com hermes-pgvector backfill e depois reconstrua os índices HNSW.

A origem e a referência completa da configuração estão no GitHub:

👉 github.com/andreab67/hermes-memory-pgvector