Erweitern Sie Ihre FastAPI-App mit der Vektorsuche von VectorAI DB

Die Integration der semantischen Suche in eine FastAPI-Anwendung ist oft mit anfänglichen Schwierigkeiten verbunden. Die meisten Anleitungen lenken Entwickler entweder zu Cloud , für die eine Kontoeinrichtung und API-Schlüssel erforderlich sind, oder zu lokalen Stacks, die von mehreren Diensten abhängig sind, bevor man überhaupt nützlichen Code schreiben kann.

Dieser Mehraufwand entsteht bereits, bevor die Funktion überhaupt entwickelt wurde, wodurch sich der Aufwand von der API-Entwicklung hin zur Einrichtung der Infrastruktur verlagert.

This tutorial takes a simpler approach. Actian VectorAI DB runs as a single Docker container and connects through a Python or a JavaScript client. For early development and prototyping, you do not need a cloud account, API keys, or multiple services. Install the database and client to begin building your API. Compared to setups that rely on managed services or multi-container stacks, this reduces setup time, costs, and moving parts.

In diesem Tutorial erstellen Sie eine kleine Produktsuch-API, um dies zu veranschaulichen. Das Ziel ist es, Nutzern die Suche nach Sinnzusammenhängen statt nach exakten Suchbegriffen zu ermöglichen. So sollte beispielsweise eine abfragen „etwas Warmes zum Anziehen im Winter“ Jacken oder Pullover als Ergebnis liefern, auch wenn diese genauen Begriffe nicht in der Produktbeschreibung vorkommen.

Am Ende dieses Tutorials verfügen Sie über eine funktionierende FastAPI-Anwendung mit semantischer Suche, die lokal läuft – und zwar mit einer Konfiguration, die Sie ohne zusätzliche Infrastruktur ausführen, testen und erweitern können.

Einrichtung

In diesem Abschnitt starten Sie VectorAI DB und richten Ihr FastAPI-Projekt mit uv ein. Am Ende verfügen Sie über eine laufende Vektordatenbank und eine Python , die für die Verbindung mit dieser bereit ist.

Voraussetzungen

Um mitzumachen, installieren Sie bitte die folgenden Tools in Ihrem lokalen Netzwerk:

• Docker und Docker Compose
• Python .10 oder höher
• PIP oder UV (In dieser Anleitung wird UV verwendet)

Actian VectorAI DB starten

Run VectorAI DB as a single Docker container. Create a docker-compose.yml file with the following content:

services:
  vectorai:
    image: williamimoh/actian-vectorai-db:latest
    platform: linux/amd64
    container_name: vectorai_db
    ports:
      - "50051:50051"
    volumes:
      # vector data persists across restarts
      - ./data:/app/data
    environment:
      - VECTORAI_LOG_LEVEL=info
    restart: unless-stopped

Start the service:

docker compose up -d

VectorAI DB läuft nun lokal auf Port 50051.

Erstellen Sie Ihr FastAPI-Projekt mit Uv

Now set up your Python project. If you do not have uv installed, install it first.

Erstellen Sie ein neues Projekt in Ihrem aktuellen Verzeichnis, indem Sie folgenden Befehl ausführen:

uv init .
uv venv

Installieren Sie FastAPI, den Python für die VectorAI-Datenbank und die Abhängigkeit für das Einbettungsmodell:

uv add fastapi uvicorn sentence-transformers

Sign up for the Actian VectorAI DB community edition. Once registered, you will receive instructions for setting up the client, either by downloading the binary or by running it with a Docker container, depending on your preference.

Install VectorAI DB Python SDK by:

uv add actian-vectorai-client

Verbindung überprüfen

Erstellen Sie ein einfaches Skript „test_connection.py , um zu überprüfen, ob Ihre App eine Verbindung zur VectorAI-Datenbank herstellt:

from actian_vectorai import VectorAIClient

VECTORAI_HOST = "localhost:50051"

with VectorAIClient(VECTORAI_HOST) as client:

    # Health check

    info = client.health_check()

    print(f"Connected to {info['title']} v{info['version']}")

Testen Sie diese Verbindung wie folgt:

uv run test_connection.py

Wenn alles funktioniert, sollte eine Meldung angezeigt werden, dass die Verbindung erfolgreich hergestellt wurde.

Verbindung prüfen

Sie können nun Ihr Datenmodell definieren und mit der Erstellung Ihrer API beginnen.

Den Ingest-Endpunkt einrichten

Sie erstellen einen POST /ingest -Endpunkt erstellen, der eine Liste von Produkten akzeptiert, jede Beschreibung einbettet und die Ergebnisse in der VectorAI-Datenbank speichert. So können Sie eine JSON-Liste von Produkten an Ihre API senden und diese für die Suche bereitstellen.

Beginnen Sie mit der Einrichtung des Datenmodells und der Sammlung. Erstellen Sie eine Datei main.py mit folgendem Inhalt:

from fastapi import FastAPI

from pydantic import BaseModel

from sentence_transformers import SentenceTransformer

from actian_vectorai import VectorAIClient, VectorParams, Distance, PointStruct, CollectionExistsError

from typing import List

from contextlib import asynccontextmanager

COLLECTION = "products_collection"

DIMENSION = 384  # all-MiniLM-L6-v2 produces 384-dimensional vectors

model = SentenceTransformer("all-MiniLM-L6-v2")

class Product(BaseModel):

    id: int

    name: str

    description: str

    category: str

    price: float

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    with VectorAIClient("localhost:50051") as client:
        try:
            client.collections.create(
                COLLECTION,
                vectors_config=VectorParams(size=DIMENSION, distance=Distance.Cosine)
            )
        except CollectionExistsError:
            pass
    yield

app = FastAPI(lifespan=lifespan)

Verwenden all-MiniLM-L6-v2 . Es handelt sich um ein Modell mit 22,7 Millionen Parametern, das auf CPU läuft CPU 384-dimensionale Vektoren erzeugt. Es bietet ausreichende Geschwindigkeit für die lokale Entwicklung und hohe Genauigkeit für die Produktsuche. Die Sammlung verwendet den Kosinusabstand, der den Winkel zwischen Vektoren misst und nicht deren Größe. Dies eignet sich gut für Text-Embeddings, da der Fokus auf der Bedeutung und nicht auf der Länge der Beschreibung liegt.

Erstellen Sie nun die Ingest-Endpunkt Endpunkt.

@app.post("/ingest")

def ingest(products: List[Product]):

    descriptions = [p.description for p in products]

    embeddings = model.encode(descriptions, convert_to_numpy=True)

    points = [

        PointStruct(

            id=p.id,

            vector=embeddings[i].tolist(),

            payload={

                "name": p.name,

                "category": p.category,

                "price": p.price,

            }

        )

        for i, p in enumerate(products)

    ]

    with VectorAIClient("localhost:50051") as client:

        client.points.upsert(COLLECTION, points)

    return {"inserted": len(points)}

Das bewirkt Folgendes:

• Extracts all product descriptions into a list so you can embed them in one batch.
• Erzeugt Einbettungen unter Verwendung des all-MiniLM-L6-v2 .
• Wandelt jedes Produkt in ein PointStruct mit einer ID, einem Vektor und einer Nutzlast.
• Speichert nützliche Metadaten Name, Kategorie und Preis zusammen mit dem Vektor.
• Fügt alle Punkte mit einer einzigen Abfrage in die VectorAI-Datenbank ein.

Such-Endpunkt erstellen

Um die fünf ähnlichsten Produkte zu ermitteln, enthält die Implementierung eine GET /search Endpunkt, der eine abfragen einen optionalen Kategoriefilter akzeptiert. Der Endpunkt bettet die abfragen ein, führt eine Vektorsuche in der VectorAI-Datenbank durch und gibt die relevantesten Ergebnisse zurück.

Mit diesem Schritt ist der Suchablauf abgeschlossen: In einem einzigen Suchvorgang wird von der Eingabe von Rohtext zu semantisch gewichteten Ergebnissen übergegangen.

Warum dieser Filter wichtig ist

Der Kategoriefilter ist der Bereich, in dem VectorAI DB die Entwicklererfahrung verbessert. Bei FAISS führt man in der Regel zunächst eine vollständige Vektorsuche durch und filtert die Ergebnisse anschließend in Python. Das bedeutet, dass Rechenleistung für Ergebnisse verschwendet wird, die man später verworfen hat.

VectorAI DB filters inside the search operation. It considers only matching vectors during retrieval. This keeps search efficient and simpler to reason about.

Implement the endpoint

Füge die folgenden Importe und den Endpunkt zu deiner main.py hinzu:

from actian_vectorai import FilterBuilder, Field

@app.get("/search")

def search(query: str, category: str = None, top_k: int = 5):

    query_vector = model.encode([query], convert_to_numpy=True)[0].tolist()

    search_filter = None

    if category:

        search_filter = FilterBuilder().must(Field("category").eq(category)).build()

    with VectorAIClient("localhost:50051") as client:

        results = client.points.search(

            COLLECTION,

            vector=query_vector,

            limit=top_k,

            filter=search_filter

        )

    return [

        {

            "id": r.id,

            "score": round(r.score, 4),

            "name": r.payload["name"],

            "category": r.payload["category"],

            "price": r.payload["price"],

        }

        for r in results

    ]

So funktioniert es

• Wandle Nutzer abfragen “abfragen eine Einbettung um.
• Erstelle einen Filter nur, wenn eine Kategorie angegeben ist.
• Übergeben Sie sowohl den Vektor als auch den Filter in einer einzigen Anfrage an VectorAI DB.
• Gib die besten Ergebnisse mit Ähnlichkeitswerten und Metadaten zurück.

Die Filterobjekte sind typisierte Python . Dies hilft FastAPI dabei, Fehler frühzeitig zu erkennen, und sorgt für abfragen einheitliche abfragen Ihrer abfragen .

When category is not provided, search_filter stays None. The search then runs across all products.

Los geht's

Starten Sie VectorAI DB und anschließend FastAPI. Zwei Befehle.

docker-compose up -d

uv run uvicorn main:app –reload

In another terminal window, ingest three sample products:

curl -X POST http://localhost:8000/ingest \

  -H "Content-Type: application/json" \

  -d '[

    {"id": 1, "name": "Cashmere Scarf", "description": "Soft cashmere scarf, ideal for cold weather", "category": "clothing", "price": 49.00},

    {"id": 2, "name": "Bluetooth Speaker", "description": "Portable waterproof speaker with 12-hour battery", "category": "electronics", "price": 59.99},

    {"id": 3, "name": "Trail Mix", "description": "Mixed nuts and dried fruit, high-energy snack", "category": "food", "price": 8.50}

  ]'

You get a response:

{“inserted”: 3}

Führen Sie eine semantische Suche mit einem Kategoriefilter durch:

curl "http://localhost:8000/search?query=something+warm+for+winter&category=clothing"

You should have the following response:

Suche nach abfragen Kategorie

Führen Sie dieselbe abfragen Filter aus, um alle Kategorien nach Relevanz sortiert anzuzeigen:

curl -s "http://localhost:8000/search?query=something+warm+for+winter" | jq

The scarf still scores highest. The speaker and trail mix return with lower scores because their descriptions carry less semantic overlap with the query.

Search query without category

Bis jetzt haben Sie die Architektur wie in der Abbildung dargestellt aufgebaut.

Übersichtsschema

Schauen wir uns an, was wir als Nächstes entwickeln.

Was soll ich als Nächstes bauen?

Diese Konfiguration eignet sich gut für die lokale Entwicklung und kleinere Arbeitslasten. Der nächste Schritt besteht darin, sie für einen höheren Durchsatz und komplexere Suchmuster vorzubereiten.

Use the async client for production workloads

Die derzeitige Implementierung nutzt einen synchronen Client, der sich zwar gut für die lokale Entwicklung und kleine Tests eignet, jedoch den Durchsatz bei Zustimmung einschränkt. Jeder Datenbankaufruf blockiert den Anfragethread bis zu seinem Abschluss, was die Gesamtleistung unter Last beeinträchtigt.

VectorAI DB provides an AsyncVectorAIClient that removes this bottleneck. It integrates with FastAPI’s async model, allowing endpoints to handle other requests while awaiting database operations. This approach is especially important for concurrent searches, batch ingestion, and background data updates.

In einer Produktionsumgebung lässt sich diese Änderung zudem gut mit dem Einsatz mehrerer uvicorn-Worker kombinieren. Zusammen ermöglichen sie eine horizontale Skalierung Ihres Dienstes, ohne dass Sie Ihre Kernlogik ändern müssen.

Hybridsuche hinzufügen

Die Vektorähnlichkeit allein funktioniert gut, wenn die abfragen vage oder beschreibend abfragen , da sie sich eher auf die Bedeutung als auf exakte Wortlaute konzentriert. In Fällen, in denen es auf Präzision ankommt – insbesondere bei Produktnamen, Modellnummern oder Markennamen –, kann sie jedoch an ihre Grenzen stoßen.

VectorAI DB combines vector similarity with keyword matching in a single query. The vector component captures semantic meaning, while the keyword component ensures exact terms are not lost in translation. Both signals contribute to the final ranking.

Die hybride Suche ist in realen Szenarien hilfreich, in denen Nutzer in ein und derselben abfragen sowohl eine semantische Absicht als auch präzise Suchkriterien kombinieren. Eine Suche wie „Nike-Laufschuhe Größe 42“ enthält beispielsweise sowohl eine semantische Absicht (Laufschuhe für den Sport) als auch exakte Suchkriterien (Nike und Größe 42). Die hybride Suche stellt sicher, dass keines dieser beiden Signale verloren geht, was die Qualität der Ergebnisse verbessert, ohne dass Sie zusätzliche Logik implementieren müssen.

Extend filtering and ranking logic

Derzeit filtert Ihre Suche nur nach Kategorien, was für eine einfache Demo ausreicht. In realen Anwendungen wird die Filterung jedoch dynamischer, da Nutzer erwarten, die Ergebnisse anhand mehrerer Kriterien einzugrenzen.

You can extend your filters to support things like price ranges, stock availability, brand names, or any other structured attribute in your dataset. VectorAI DB’s typed filter system makes this easier because you build filters as structured Python objects rather than ad-hoc query dictionaries. This reduces errors and keeps your search logic consistent with the rest of your FastAPI application.

Mit Datensatz des Datensatz werden diese Filter unverzichtbar, um den Ergebnisraum vor der Rangfolge zu steuern. Die Vektorsuche sorgt weiterhin für die Relevanz, während die Filterung den Datensatz Datensätze einschränkt, die Nutzer entsprechen.

Zum Abschluss

In diesem Tutorial haben Sie ein vollständiges semantisches Suchsystem mit FastAPI und VectorAI DB erstellt. Sie haben aus einem leeren Projekt eine funktionsfähige API entwickelt, die Anfragen in natürlicher Sprache versteht und relevante Ergebnisse liefert, die auf der Bedeutung und nicht nur auf Schlüsselwörtern basieren.

Sie haben eine Erfassungspipeline erstellt, die Produktbeschreibungen mithilfe von all-MiniLM-L6-v2 und diese in einer Vektorsammlung mit Metadaten speichert. Anschließend haben Sie einen Such-Endpunkt erstellt, der Nutzer einbettet und die relevantesten Produkte anhand der Vektorähnlichkeit abruft, mit optionaler Filterung nach strukturierten Einschränkungen wie der Kategorie.

Um eine FastAPI-Anwendung um eine Vektorsuche zu erweitern, sind weder ein komplexer Stack noch Cloud externer Cloud erforderlich. VectorAI DB läuft als einzelner Container und lässt sich direkt über einen Python integrieren, sodass der Übergang von der Einrichtung zur Implementierung schnell und einfach vonstattengeht.

From here, you can extend the system with async clients, hybrid search, and richer filtering logic as your application grows into more production-ready workloads.

Aktuelle Informationen und Details zur Implementierung finden Sie in der DokumentationVektor-KI und Lager GitHub.

Registrieren Sie sich für die Actian VectorAI DB Community Edition und legen Sie noch heute los.

Über den Autor

Über Nick Johnson

Nick Johnson ist Senior Product Marketing Manager bei Actian und verantwortlich für den Markteinführungserfolg von HCL Informix und Actian Zen. Er hat sich in seiner Karriere der Entwicklung überzeugender Botschaften und Strategien für Datenbanken verschrieben und bringt einen reichen Erfahrungsschatz aus seiner erfolgreichen Tätigkeit bei führenden Technologieunternehmen wie Neo4j, Microsoft und SAS mit.