Luo upotukset
Tällä sivulla
Koodaa palat vektoreiksi
Asiakirjasi on nyt pilkottu siisteihin paloihin. Seuraava vaihe on muuntaa ne upotuksiksi (embeddings) käyttämällä mistral-embed-rajapintaa ja tallentaa nämä vektorit vektoritietokantaan, joka toimii hakukoneenasi. Tässä vaiheessa tekstikokoelmasi lakkaa olemasta pelkkää tekstiä ja muuttuu kyselykelpoiseksi geometriaksi. Muutama tekninen varotoimi – eräajot, uudelleenyritykset ja pysyvyys – tekevät eron hauraan prototyypin ja luotettavan hakemiston välillä.
Pienelle kokoelmalle, esimerkiksi alle sadalle palalle, yksi suora kutsu riittää. Poimi teksti palasanakirjoistasi, syötä ne sellaisinaan rajapinnalle ja hae koko matriisi. Suorituksen lopussa näkyvä muoto (87, 1024) on ensimmäinen sanityyttitarkistuksesi: rivejä on yhtä monta kuin paloja, ja sarakkeita on 1024, koska se on mistral-embed-mallin ulottuvuus. Jos rivimäärä ei täsmää, erään on lipsahtanut mukaan tyhjä pala.
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
# Oletetaan, että chunks on lista valmisteltuja paloja
chunk_texts = [c["text"] for c in chunks]
# Koodaus yhdellä kutsulla
response = client.embeddings.create(
model="mistral-embed",
inputs=chunk_texts,
)
embeddings = np.array([d.embedding for d in response.data])
print(f"Upotukset: {embeddings.shape}")
# Upotukset: (87, 1024) esimerkkinä
Eräkoodaus
Muutaman kymmenen palan jälkeen yksi kutsu törmää rajapinnan rajoituksiin. Ratkaisu on jakaa lista eriin ja yhdistää tulokset. Alla oleva funktio käsittelee 25 palan osia ja näyttää edistymisen. Tämä ei ole vain kosmeettista: useiden tuhansien palojen kokoelmassa koodaus vie useita minuutteja, ja haluat tietää, missä vaiheessa prosessi on, sen sijaan että tuijottaisit mykkää päätettä. Järjestys säilyy, joten jokainen vektori pysyy linjassa vastaavan palan kanssa alkuperäisessä listassasi.
def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
"""Koodaa lista paloja erissä."""
texts = [c["text"] for c in chunks]
all_embeddings = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
print(f" Koodataan erä {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
f"({len(batch)} palaa)...")
response = client.embeddings.create(
model=model,
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
return np.array(all_embeddings)
# Koodaa kaikki palat
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Yhteensä: {embeddings.shape[0]} vektoria, joissa {embeddings.shape[1]} ulottuvuutta")
Selviytyminen verkkovirheistä
Tuotantoympäristössä rajapintakutsu epäonnistuu ennemmin tai myöhemmin: verkkoyhteys katkeaa, nopeusrajoitus osuu kohdalle tai palvelu on väliaikaisesti alhaalla. Ilman suojauksia indeksointisi pysähtyy erään 180 kohdalla 400:sta, ja olet taas lähtöruudussa. Robusti versio käärii jokaisen erän uudelleenyrityssilmukkaan, jossa käytetään eksponentiaalista viivytystä (exponential backoff) – yksi sekunti, sitten kaksi, sitten neljä. Tämä kasvava väli on tärkeä: uudelleenyritys heti kiintiön hylkäyksen jälkeen vain pahentaa tilannetta. Kolmen peräkkäisen epäonnistumisen jälkeen funktio nostaa nimenomaisen poikkeuksen, joka nimeää viallisen erän, sen sijaan että palauttaisi typistyneen matriisin, jossa virhe paljastuisi vasta haun aikana.
import time
def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
"""Robusti koodaus virheenkäsittelyllä."""
texts = [c["text"] for c in chunks]
all_embeddings = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
for attempt in range(max_retries):
try:
response = client.embeddings.create(
model="mistral-embed",
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
break # Onnistui, poistu uudelleenyrityssilmukasta
except Exception as e:
wait_time = 2 ** attempt # Eksponentiaalinen viivytys: 1s, 2s, 4s
print(f" Virhe erässä {i // batch_size + 1}, "
f"yritys {attempt + 1}/{max_retries}: {e}")
if attempt < max_retries - 1:
print(f" Odotetaan {wait_time}s ennen uudelleenyritystä...")
time.sleep(wait_time)
else:
raise RuntimeError(
f"Epäonnistui {max_retries} yrityksen jälkeen erälle {i // batch_size + 1}"
)
return np.array(all_embeddings)
Tallenna hakemisto levylle
Jokainen koodauskerta maksaa aikaa ja laskutettavia rajapintakutsuja. Vektorien uudelleenlaskeminen joka kerta sovelluksen käynnistyessä on puhdasta hukkaa, varsinkin kun itse kokoelma ei ole muuttunut. Tallennus tapahtuu kahteen täydentävään tiedostoon: vektorit menevät NumPyyn, joka on kompakti binäärimuoto ja latautuu välittömästi, kun taas metatiedot – teksti, lähde, sijainti – menevät luettavaan JSON-tiedostoon, jonka voit avata tarkistaaksesi epäilyttävän palan. Nämä kaksi tiedostoa ovat toisistaan riippuvaisia ja linkittyvät rivijärjestyksen kautta: älä koskaan luo toista ilman toista, muuten hakutuloksesi viittaavat vääriin teksteihin.
import json
def save_index(chunks, embeddings, filepath="rag_index"):
"""Tallenna palat ja upotukset."""
# Tallenna upotukset (NumPy)
np.save(f"{filepath}_embeddings.npy", embeddings)
# Tallenna metatiedot (JSON)
metadata = []
for c in chunks:
metadata.append({
"text": c["text"],
"source": c.get("source", ""),
"chunk_index": c.get("chunk_index", 0),
})
with open(f"{filepath}_metadata.json", "w", encoding="utf-8") as f:
json.dump(metadata, f, ensure_ascii=False, indent=2)
print(f"Hakemisto tallennettu: {len(chunks)} palaa, {embeddings.shape}")
def load_index(filepath="rag_index"):
"""Lataa palat ja upotukset levyltä."""
embeddings = np.load(f"{filepath}_embeddings.npy")
with open(f"{filepath}_metadata.json", "r", encoding="utf-8") as f:
metadata = json.load(f)
print(f"Hakemisto ladattu: {len(metadata)} palaa, {embeddings.shape}")
return metadata, embeddings
# Tallenna
save_index(chunks, embeddings)
# Lataa (seuraavassa käynnistyksessä)
chunks_loaded, embeddings_loaded = load_index()
Varmista ennen jatkamista
Hiljaisesti vioittunut hakemisto paljastuu myöhään, yleensä vasta kun käyttäjä ilmoittaa absurdist vastauksesta. Muutama offline-tarkistus vie kolmekymmentä sekuntia ja säästää sinut tältä löytöretkeltä. Varmistusfunktio näyttää ensin perusmittarit – palojen määrä, ulottuvuus, keskimääräinen normi – ja mittaa sitten vierekkäisten palojen samankaltaisuutta: koska ne tulevat samasta asiakirjasta, niiden pitäisi näyttää merkittävästi korkeampia arvoja kuin kahden satunnaisen kohdan. Viimeinen testi on yksinkertaisin ja paljastavin: pala verrattuna itseensä tuottaa täsmälleen arvon 1.0. Mikä tahansa muu arvo kertoo kohdistusongelmasta tai numeerisesta muunnosvirheestä.
from sklearn.metrics.pairwise import cosine_similarity
def verify_embeddings(chunks, embeddings, n_tests=5):
"""Varmista upotusten laatu yksinkertaisilla testeillä."""
print("=== Varmistetaan upotukset ===")
print(f"Palojen määrä: {len(chunks)}")
print(f"Ulottuvuudet: {embeddings.shape[1]}")
print(f"Keskimääräinen normi: {np.linalg.norm(embeddings, axis=1).mean():.4f}")
# Testi: saman asiakirjan palojen pitäisi olla lähempänä toisiaan
for i in range(min(n_tests, len(chunks) - 1)):
sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
print(f" Samankaltaisuus pala {i} <-> {i+1}: {sim:.4f}")
# Testi: pala verrattuna itseensä = 1.0
self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
print(f" Itsesamankaltaisuus (täytyy olla 1.0): {self_sim:.6f}")
verify_embeddings(chunks, embeddings)
Yhdistettynä työnkulku tiivistyy neljään hyödylliseen riviin. Valmistele palat edellisen oppitunnin putkella, koodaa robustissa tilassa, varmista ja tallenna. Tämä on skripti, jonka ajat uudelleen aina, kun kokoelma päivittyy.
# 1. Valmistele palat (edellinen oppitunti)
chunks = prepare_documents(raw_docs)
# 2. Koodaa
embeddings = encode_chunks_robust(chunks, batch_size=25)
# 3. Varmista
verify_embeddings(chunks, embeddings)
# 4. Tallenna
save_index(chunks, embeddings)
print("Hakemisto valmis hakuun!")
Keskeiset asiat
- Käytä eräajoja suurten kokoelmien koodaamiseen (25–50 palan eriä)
- Lisää uudelleenyrityslogiikka eksponentiaalisella viivytyksellä luotettavuuden vuoksi
- Tallenna upotukset levylle (NumPy) välttääksesi uudelleenlaskennan
- Pidä metatiedot (teksti, lähde, sijainti) erillisessä JSON-tiedostossa
- Varmista upotusten laatu ennen niiden käyttöönottoa tuotannossa