Aggiungere Memoria al Tuo Agente Weaviate: Un Tutorial Pratico di 2500 Parole
Se vuoi che il tuo agente intelligente si ricordi realmente del contesto tra le conversazioni, devi weaviate add memory to your agent nel modo giusto, utilizzando la ricerca vettoriale per memorizzare e richiamare le interazioni precedenti. Non stiamo semplicemente creando dei pezzi di codice in un database; stiamo costruendo un vero grafo della conoscenza arricchito con una ricerca semantica che mantiene il tuo agente vigile.
Cosa Stai Costruendo e Perché È Importante
Stiamo costruendo un agente che utilizza Weaviate per la memorizzazione della memoria affinché possa avere conversazioni significative, non solo domande e risposte senza stato. Dimentica quelle dimostrazioni superficiali di chatbot che resettano ogni domanda — si tratta di una persistenza contestuale che i tuoi utenti percepiranno realmente.
Prerequisiti
- Python 3.11+
- Weaviate Community Edition (ultima versione stabile, ho usato 1.19.0)
- Pacchetti Pip:
weaviate-client>=4.16.0,requests,dotenv - Chiave API OpenAI o qualsiasi altra chiave API di modello di incorporazione (GPT-4, Cohere o Huggingface)
- Docker installato (opzionale ma consigliato per eseguire Weaviate localmente)
- Comprensione di base delle database vettoriali e della generazione di incorporazioni
Statistiche Veloci su Weaviate
| Metrica | Valore |
|---|---|
| Stelle GitHub | 15.839 |
| Forks | 1.227 |
| Problemi Aperti | 582 (al 20 marzo 2026) |
| Licenza | BSD-3-Clause |
| Ultimo Aggiornamento | 20 marzo 2026 |
Questi numeri mostrano che Weaviate è maturo ma resta attivo; non resterai bloccato ad aspettare una libreria abbandonata.
Passo dopo Passo: Aggiungere Memoria al Tuo Agente Weaviate
Passo 1: Configurare il Server Weaviate
# Esegui Weaviate con Docker per test locali rapidi
docker run -d \
-p 8080:8080 \
-e AUTH_ANONYMOUS_ACCESS_ENABLED=true \
-e QUERY_DEFAULTS_LIMIT=20 \
-e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
-v $(pwd)/weaviate_data:/var/lib/weaviate \
semitechnologies/weaviate:latest
Perché è importante: Weaviate supporta la persistenza e l’accesso anonimo per impostazione predefinita qui, il che rende più facile lo sviluppo locale. Impostando QUERY_DEFAULTS_LIMIT=20, eviti di incontrare noiose limitazioni di 10 risultati sulle query, il che infastidisce anche gli sviluppatori più esperti. Ricorda, se non desideri accesso anonimo, configura le chiavi API. Ma per i test, va bene.
Errori comuni: Se il contenitore va in crash, verifica che la porta 8080 sia libera. A volte, Docker Desktop o contenitori precedenti la occupano. Inoltre, se generi incorporazioni più velocemente di quanto Weaviate possa gestire (raro in locale), aspettati un ritardo.
Passo 2: Definire uno Schema per la Memoria del Tuo Agente
import weaviate
client = weaviate.Client("http://localhost:8080")
schema = {
"classes": [
{
"class": "MemoryEntry",
"description": "Memorizza un segmento unico di memoria per l'agente",
"properties": [
{
"name": "text",
"dataType": ["text"],
"description": "Il contenuto testuale della memoria."
},
{
"name": "embedding",
"dataType": ["number[]"],
"description": "Rappresentazione dell'incorporazione vettoriale."
},
{
"name": "timestamp",
"dataType": ["date"],
"description": "Quando la memoria è stata memorizzata."
}
],
"vectorizer": "none" # Inietteremo noi stessi le incorporazioni
}
]
}
client.schema.delete_all() # Ripristino pulito
client.schema.create(schema)
Perché niente vectorizer? L’errore principale che commettono i principianti è utilizzare ciecamente i vectorizer di testo predefiniti di Weaviate. Va bene per una ricerca di testo semplice, ma quando vuoi un controllo rigoroso sul tuo modello di incorporazione (ad esempio, OpenAI, Cohere), devi caricare i vettori da solo. Questo evita la confusione dei tutorial concorrenti che abusano dei vectorizer incorporati di Weaviate per gli agenti.
Eliminare lo schema prima di crearlo forza un nuovo inizio, preservandoti da errori strani « lo schema esiste già ». Certo, questo cancella i dati, ma si tratta di sviluppo locale.
Passo 3: Generare e Caricare le Incorporazioni di Memoria
import os
import requests
from datetime import datetime
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
def get_openai_embedding(text):
resp = requests.post(
"https://api.openai.com/v1/embeddings",
headers={"Authorization": f"Bearer {OPENAI_API_KEY}"},
json={"input": text, "model": "text-embedding-ada-002"}
)
resp.raise_for_status()
return resp.json()["data"][0]["embedding"]
def add_memory_entry(client, text):
embedding = get_openai_embedding(text)
memory_obj = {
"text": text,
"embedding": embedding,
"timestamp": datetime.utcnow().isoformat()
}
client.data_object.create(memory_obj, "MemoryEntry", vector=embedding)
# Esempio di utilizzo
add_memory_entry(client, "Ricordo che il cielo è blu.")
add_memory_entry(client, "Il senso della vita è 42.")
Perché generare le incorporazioni da solo? Perché è estremamente prezioso separare la generazione di incorporazioni e la memorizzazione di vettori. Potresti aver bisogno di cambiare il tuo modello di incorporazione in seguito o di aggregare vettori da fonti diverse. Questi altri tutorial mescolano tutto e ti ritrovi bloccato.
Errore comune qui: dimenticare di passare l’incorporazione come parametro vettore vector=embedding nella chiamata data_object.create. Se dimentichi questo, Weaviate cercherà di vettorizzarlo automaticamente (e fallirà perché abbiamo impostato vectorizer: none).
Passo 4: Interrogare la Memoria con una Ricerca Semantica
def query_memory(client, question, top_k=3):
question_embedding = get_openai_embedding(question)
near_vector = {"vector": question_embedding}
response = client.query.get("MemoryEntry", ["text", "timestamp"])\
.with_near_vector(near_vector)\
.with_limit(top_k)\
.do()
results = response.get("data", {}).get("Get", {}).get("MemoryEntry", [])
return results
# Provalo
results = query_memory(client, "Di che colore è il cielo?")
for res in results:
print(f"Memoria: {res['text']} (memorizzata il {res['timestamp']})")
Perché la ricerca semantica? La ricerca per parole chiave nella memoria è inutile per gli agenti che devono gestire conversazioni a più turni con richieste sfumate. La vera magia risiede nella ricerca di incorporazioni per « pensieri simili » senza sovrapposizione esatta di parole chiave.
La funzionalità chiave è il modo in cui mescoli e abbini queste query dinamicamente all’esecuzione per mantenere il tuo agente consapevole del contesto senza essere sopraffatto da ricordi irrilevanti.
Passo 5: Collegare il Tuo Agente alla Memoria Weaviate
class MemoryAgent:
def __init__(self, weaviate_client):
self.client = weaviate_client
def remember(self, text):
add_memory_entry(self.client, text)
def recall(self, question):
return query_memory(self.client, question, top_k=5)
def chat(self, question):
memories = self.recall(question)
# Concatenazione semplice per il prompt — sostituisci con il tuo modello di prompt
prompt_context = "\n".join([m["text"] for m in memories])
prompt = f"Contesto:\n{prompt_context}\n\nDomanda: {question}\nRisposta:"
# Invia il prompt al LLM (non coperto qui)
# Simulazione:
return f"Risposta simulata basata sulle memorie:\n{prompt}"
agent = MemoryAgent(client)
agent.remember("L'agente è stato creato il 20 marzo 2026.")
agent.remember("Python è il linguaggio di programmazione riconosciuto per l'IA.")
print(agent.chat("Quando è stato creato l'agente?"))
Perché questo design? Separare la gestione della memoria dalla logica di « chat » dell’agente è cruciale. Odio il codice strettamente accoppiato dove la gestione del contesto rende il tuo chiamata di generazione disordinata. Con questo modello, segui, memorizzi e richiami in modo indipendente. Se desideri cambiare per un miglior LLM, o aggiungere caching, è banale.
I Traps Che Non Sentirai in Altri Tutorial
- Confusione riguardo allo schema. Molti tutorial passano rapidamente sulla progettazione dello schema, ma se il tuo schema è errato, i tuoi vettori e metadati sono spazzatura. Rimpiangerai di non aver previsto timestamp o metadati come ID utente per filtrare la tua memoria.
- I costi delle incorporazioni contano. Le incorporazioni OpenAI non sono gratuite. Se aggiungi migliaia di memorie, preparati a una fattura. Raggruppa la tua generazione per ridurre i costi e memorizza in cache le incorporazioni in modo aggressivo.
- La memoria eccessiva uccide le performance. Interrogare un database vettoriale con decine di migliaia di voci? Vedrai picchi di latenza e risultati di richiamo rumorosi. È necessaria una potatura regolare – una dura ma inevitabile realtà.
- Incompatibilità delle dimensioni vettoriali. Se scambi accidentalmente modelli di incorporazione o versioni, i tuoi vettori archiviati non corrisponderanno ai vettori di query. Non otterrai risultati o avrai corrispondenze fuorvianti. Fissa sempre la versione del tuo modello di incorporazione nel tuo pipeline.
- La coerenza dei dati è un problema. Senza supporto per le transazioni, scritture o aggiornamenti parziali possono lasciare memorie in sospeso senza contesto. Questo bug sottile può perseguitarti in produzione, soprattutto se aggiorni le memorie.
Esempio Completo Funzionale
import os
import requests
from datetime import datetime
import weaviate
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
WEAVIATE_URL = "http://localhost:8080"
def get_openai_embedding(text):
r = requests.post(
"https://api.openai.com/v1/embeddings",
headers={"Authorization": f"Bearer {OPENAI_API_KEY}"},
json={"input": text, "model": "text-embedding-ada-002"},
)
r.raise_for_status()
return r.json()["data"][0]["embedding"]
client = weaviate.Client(WEAVIATE_URL)
client.schema.delete_all()
schema = {
"classes": [
{
"class": "MemoryEntry",
"description": "Memorizza la memoria dell'agente",
"properties": [
{"name": "text", "dataType": ["text"]},
{"name": "embedding", "dataType": ["number[]"]},
{"name": "timestamp", "dataType": ["date"]}
],
"vectorizer": "none"
}
]
}
client.schema.create(schema)
def add_memory(text):
embedding = get_openai_embedding(text)
data = {"text": text, "embedding": embedding, "timestamp": datetime.utcnow().isoformat()}
client.data_object.create(data, "MemoryEntry", vector=embedding)
def query_memories(question, top_k=5):
q_emb = get_openai_embedding(question)
near_vector = {"vector": q_emb}
res = client.query.get("MemoryEntry", ["text", "timestamp"])\
.with_near_vector(near_vector).with_limit(top_k).do()
return res.get("data", {}).get("Get", {}).get("MemoryEntry", [])
class Agent:
def __init__(self, client):
self.client = client
def remember(self, text):
add_memory(text)
def chat(self, question):
memories = query_memories(question)
context = "\n".join([m["text"] for m in memories])
prompt = f"Contesto:\n{context}\n\nDomanda: {question}\nRisposta:"
# Risposta fittizia
return prompt
agent = Agent(client)
agent.remember("Il cielo è blu.")
agent.remember("L'acqua bolle a 100 gradi Celsius.")
print(agent.chat("Qual è il colore del cielo?"))Cosa fare dopo?
Dopo aver padroneggiato l’integrazione della memoria Weaviate, il tuo prossimo passo concreto è costruire una pipeline di dimensionamento e aggiornamento della memoria. Ciò significa valutare periodicamente quali memorie sono obsolete o non pertinenti e rimuoverle o aggiornarle. Se lasci crescere la memoria senza controllo, le risposte del tuo agente rallenteranno e diventeranno incoerenti.
Considera di implementare un sistema di obsolescenza basato sul tempo o una classificazione dell’importanza delle memorie per mantenere leggera la tua banca dati. Questo affinerà il focus dell’agente su ciò che conta davvero.
FAQ
Perché dovrei disattivare il vettorizzatore integrato di Weaviate?
I vettorizzatori integrati sono adatti per demo semplici, ma ti legano al loro modello di incorporazione specifico e rendono impossibili gli aggiornamenti. Vuoi iniettare le tue stesse incorporazioni generate da modelli come il text-embedding-ada-002 di OpenAI, per controllare la qualità dei vettori e i costi API.
Cosa fare se le mie query non restituiscono risultati?
Per prima cosa, conferma che le dimensioni delle tue incorporazioni corrispondano. Le incorporazioni ada-002 di OpenAI sono vettori di 1536 dimensioni. Se i tuoi vettori archiviati e i tuoi vettori di query differiscono in dimensioni, la ricerca di similarità non restituisce nulla. Controlla anche che il vettorizzatore del tuo schema sia ‘none’ e che tu stia inviando esplicitamente i tuoi vettori durante la creazione degli oggetti.
Come gestire i costi di incorporazione con migliaia di memorie?
Batch embed i tuoi dati invece di effettuare chiamate singole e memorizza in cache le incorporazioni su disco o Redis. La pre-elaborazione delle nuove informazioni offline può anche aiutare. Sii anche strategico riguardo a ciò che memorizzi: memorizza riassunti, non conversazioni complete. Infine, esplora modelli open-source più economici, ma fai attenzione alla precisione.
Raccomandazioni per i Personas Sviluppatori
| Tipo di Sviluppatore | Passi Successivi Raccomandati |
|---|---|
| Ricercatore in IA | Integra Weaviate con incorporazioni di trasformatori personalizzati ed esplora la ricercaibrida combinando testo e similarità di vettore. |
| Ingegnere Backend | Implementa la gestione del ciclo di vita della memoria con dimensionamento automatico, ricostruzione dell’indice e monitoraggio della sostenibilità. |
| Sviluppatore Full-Stack | Costruisci un’interfaccia utente per visualizzare e gestire le voci di memoria, e collega la memoria Weaviate con la tua interfaccia di chat frontend. |
Dati aggiornati al 21 marzo 2026. Fonti: https://github.com/weaviate/weaviate, https://weaviate.io/product/integrations/mem0
Articoli Correlati
- Migliora i LLM con Grafi di Conoscenza Affidabili: L’Innovazione di Qinggang Zhang
- Sblocca il Tuo Marchio: Progetta il Logo Perfetto di una Rete Neurale Convoluzionale
- Perché Utilizzare l’Architettura di Agente IA
🕒 Published: