Премини към основното съдържание
Български— Изберете език
Меню

Създаване на вграждания (Embeddings)

Урок 11 от 18 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Кодирате парчетата във вектори
  2. Групово кодиране (Batch Encoding)
  3. Оцеляване при мрежови грешки
  4. Запазване на индекса на диска
  5. Проверка преди продължаване
  6. Ключови изводи

Кодирате парчетата във вектори

Вашите документи вече са разделени на чисти парчета. Следващата стъпка е да ги трансформирате във вграждания (embeddings), използвайки API на mistral-embed, и след това да съхраните тези вектори във векторно хранилище, което ще действа като ваша търсачка. Това е моментът, в който вашият корпус спира да бъде обикновен текст и се превръща в геометрия, подлежаща на заявки. Няколко инженерни предпазни мерки – групиране на заявки (batching), повторни опити и постоянство – правят разликата между крехък прототип и надежден индекс.

За малък корпус, да речем по-малко от сто парчета, е достатъчно едно директно извикване. Извлечете текста от речниците с парчета, предайте ги както са на API и извлечете пълната матрица. Формата (87, 1024), показана в края на изпълнението, е първата ви проверка за здраве: толкова редове, колкото парчета, и 1024 колони, защото това е размерността на mistral-embed. Ако броят на редовете не съвпада, някое празно парче се е промъкнало в партидата.

import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

# Assume chunks is the list of our prepared chunks
chunk_texts = [c["text"] for c in chunks]

# Encode in a single call
response = client.embeddings.create(
    model="mistral-embed",
    inputs=chunk_texts,
)

embeddings = np.array([d.embedding for d in response.data])
print(f"Embeddings: {embeddings.shape}")
# Embeddings: (87, 1024) for example

Групово кодиране (Batch Encoding)

Отвъд няколко десетки парчета, едно единствено извикване удря лимитите на API. Решението е да разделите списъка на партиди и да конкатенирате резултатите. Функцията по-долу обработва срезове от по 25 елемента и показва напредъка. Това не е козметика: при корпус от няколко хиляди парчета кодирането отнема няколко минути и ще искате да знаете къде се намира процесът, вместо да гледате в безмълвен терминал. Редът се запазва, така че всеки вектор остава подравнен със съответното му парче в оригиналния списък.

def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
    """Encode a list of chunks in batches."""
    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"  Encoding batch {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
              f"({len(batch)} chunks)...")

        response = client.embeddings.create(
            model=model,
            inputs=batch,
        )
        all_embeddings.extend([d.embedding for d in response.data])

    return np.array(all_embeddings)

# Encode all chunks
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Total: {embeddings.shape[0]} vectors of {embeddings.shape[1]} dimensions")

Оцеляване при мрежови грешки

В производствена среда API извикването рано или късно ще се провали: прекъсване на мрежата, достигнат лимит на честотата или временна неизправност. Без защита индексирането ви спира на партида 180 от 400 и се връщате в началото. Надеждната версия обгръща всяка партида в цикъл за повторен опит с експоненциално забавяне – една секунда, после две, после четири. Това нарастващо разстояние е важно: повторният опит веднага след отхвърляне поради квота само влошава нещата. След три последователни неуспеха функцията поражда изрично изключение, посочващо дефектната партида, вместо да върне съкратена матрица, където бихте открили пропуска едва по време на търсенето.

import time

def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
    """Robust encoding with error handling."""
    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  # Success, exit retry loop

            except Exception as e:
                wait_time = 2 ** attempt  # Exponential backoff: 1s, 2s, 4s
                print(f"  Error in batch {i // batch_size + 1}, "
                      f"attempt {attempt + 1}/{max_retries}: {e}")
                if attempt < max_retries - 1:
                    print(f"  Waiting {wait_time}s before retry...")
                    time.sleep(wait_time)
                else:
                    raise RuntimeError(
                        f"Failed after {max_retries} attempts for batch {i // batch_size + 1}"
                    )

    return np.array(all_embeddings)

Запазване на индекса на диска

Всяко изпълнение на кодиране струва време и таксувани API извиквания. Преизчисляването на вектори всеки път, когато приложението ви стартира, е чиста загуба, особено след като самият корпус не се е променил. Запазването става в два допълващи се файла: векторите отиват в NumPy – компактен двоичен формат, който се зарежда мигновено, докато метаданните – текст, източник, позиция – отиват в четим JSON, който можете да отворите, за да проверите подозрително парче. Двата файла са взаимозависими, свързани чрез реда на редовете: никога не регенерирайте единия без другия, иначе резултатите от търсенето ви ще сочат към грешни текстове.

import json

def save_index(chunks, embeddings, filepath="rag_index"):
    """Save chunks and embeddings."""
    # Save embeddings (NumPy)
    np.save(f"{filepath}_embeddings.npy", embeddings)

    # Save metadata (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"Index saved: {len(chunks)} chunks, {embeddings.shape}")


def load_index(filepath="rag_index"):
    """Load chunks and embeddings from disk."""
    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"Index loaded: {len(metadata)} chunks, {embeddings.shape}")
    return metadata, embeddings

# Save
save_index(chunks, embeddings)

# Load (on next startup)
chunks_loaded, embeddings_loaded = load_index()

Проверка преди продължаване

Тихо повреден индекс се проявява късно, обикновено когато потребител съобщи за абсурден отговор. Няколко офлайн проверки отнемат тридесет секунди и ви спасяват от това откритие. Функцията за проверка първо показва основни метрики – брой парчета, размерност, средна норма – след което измерва сходството между съседни парчета: тъй като идват от един и същи документ, те трябва да показват значително по-високи стойности от два случайни пасажа. Последният тест е най-простият и най-разкриващият: парче, сравнено със самото себе си, трябва да даде точно 1.0. Всяка друга стойност сигнализира за проблем с подравняването или числено преобразуване.

from sklearn.metrics.pairwise import cosine_similarity

def verify_embeddings(chunks, embeddings, n_tests=5):
    """Verify embedding quality with simple tests."""
    print("=== Verifying embeddings ===")
    print(f"Number of chunks: {len(chunks)}")
    print(f"Dimensions: {embeddings.shape[1]}")
    print(f"Average norm: {np.linalg.norm(embeddings, axis=1).mean():.4f}")

    # Test: chunks from the same document should be closer
    for i in range(min(n_tests, len(chunks) - 1)):
        sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
        print(f"  Similarity chunk {i} <-> {i+1}: {sim:.4f}")

    # Test: a chunk compared to itself = 1.0
    self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
    print(f"  Self-similarity (must be 1.0): {self_sim:.6f}")

verify_embeddings(chunks, embeddings)

Свързани заедно, работният поток се свежда до четири полезни реда. Подготвяте парчетата с пайплайна от предишния урок, кодирате в надежден режим, проверявате и запазвате. Това е скриптът, който ще стартирате отново всеки път, когато корпусът се актуализира.

# 1. Prepare chunks (previous lesson)
chunks = prepare_documents(raw_docs)

# 2. Encode
embeddings = encode_chunks_robust(chunks, batch_size=25)

# 3. Verify
verify_embeddings(chunks, embeddings)

# 4. Save
save_index(chunks, embeddings)

print("Index ready for search!")

Ключови изводи

  • Използвайте групиране (batching), за да кодирате големи корпуси (партиди от 25–50 парчета)
  • Добавете логика за повторен опит с експоненциално забавяне за надеждност
  • Запазете вгражданията на диска (NumPy), за да избегнете преизчисляване
  • Пазете метаданните (текст, източник, позиция) в отделен JSON файл
  • Проверете качеството на вгражданията, преди да ги използвате в производство