Askolia für Convex: Suche, Antworten mit Quellen und Dokumentsynchronisierung

23. Oktober 2026Appik Studio

Die erste Version von @appik-studio/askolia-convex ist auf npm verfügbar. Version 0.1.0 verbindet eine Convex-Anwendung mit Askolia für Suche, KI-Antworten mit Quellen und die Synchronisierung öffentlicher Dokumente. Das Paket steht unter der MIT-Lizenz.

Ihre Mutation speichert einen Synchronisierungsauftrag zusammen mit der Datenänderung. Die Komponente übermittelt ihn nach dem Commit an Askolia, verfolgt seinen Status und wiederholt die Übertragung bei geeigneten Fehlern. Suche und Fragen führen Sie aus Ihren Convex-Actions aus.

Die Komponente installieren und registrieren

Sie benötigen Convex 1.46 oder neuer sowie ein Askolia-Backend mit der passenden bereitgestellten Integrations-API. Installieren Sie das Paket in Ihrer Convex-Anwendung:

bun add @appik-studio/askolia-convex@0.1.0 convex@^1.46.0

Registrieren Sie die Komponente und übergeben Sie ihre serverseitigen Umgebungsvariablen:

// convex/convex.config.ts
import { defineApp } from "convex/server";
import { v } from "convex/values";
import askolia from "@appik-studio/askolia-convex/convex.config.js";

const app = defineApp({
  env: {
    ASKOLIA_URL: v.optional(v.string()),
    ASKOLIA_API_KEY: v.optional(v.string()),
  },
});
app.use(askolia, {
  env: {
    ASKOLIA_URL: app.env.ASKOLIA_URL,
    ASKOLIA_API_KEY: app.env.ASKOLIA_API_KEY,
  },
});
export default app;

Setzen Sie für das gehostete Askolia ASKOLIA_URL auf https://tacit-goose-489.eu-west-1.convex.site. Wenn Sie Ihr eigenes Askolia-Backend betreiben, verwenden Sie den HTTPS-Ursprung seiner HTTP-Actions. Die Dashboard-Adresse und die .convex.cloud-Adresse sind dafür nicht geeignet.

Für einen gehosteten Integrationsschlüssel kontaktieren Sie Appik Studio und nennen Ihr Askolia-Projekt. Das Team richtet die Schlüssel derzeit mit Ihnen ein; im Dashboard gibt es dafür noch keine Verwaltung. Setzen Sie den erhaltenen ASKOLIA_API_KEY in den Umgebungsvariablen Ihres Convex-Deployments. Der Schlüssel bleibt auf dem Server. Betreiber eines eigenen Askolia-Backends können mit der authentifizierten Mutation integrationApi:createKey einen Integrationstoken erstellen und projectId und label übergeben. Die Mutation gibt den Token nur einmal zurück. Diese Verwaltungsfunktion gehört zu Askolia, nicht in Ihre eigene Anwendung. Ein öffentlicher Widget-Schlüssel, ein Convex-Administratorschlüssel oder ein Session-Cookie ersetzt den Token nicht.

Verwenden Sie für jedes Entwicklungs-, Preview- und Produktionsdeployment ein separates Askolia-Projekt mit eigenem Schlüssel. Hinterlegen Sie Produktionstoken niemals als Preview-Standardwerte. Ohne Zugangsdaten gelingt die Installation, Anfragen schlagen jedoch fehl.

Askolia rechnet pro Projekt ab. Zusätzliche Umgebungsprojekte können deshalb die Abonnementkosten erhöhen. Lassen Sie Zugangsdaten in Previews ohne Integration unkonfiguriert. Für isolierte automatisierte Tests verwenden Sie den Test-Helper des Pakets mit simuliertem Transport.

Erstellen Sie einen Client, nachdem Convex die Komponententypen generiert hat:

// convex/askolia.ts
import { Askolia } from "@appik-studio/askolia-convex";
import { components } from "./_generated/api";

export const askolia = new Askolia(components.askolia);

Aus Actions suchen und Fragen stellen

Übergeben Sie innerhalb einer Convex-Action deren Kontext an den Client:

const matches = await askolia.search(ctx, {
  query: "How long does delivery take?",
  locale: "en",
  limit: 5,
});

const result = await askolia.ask(ctx, {
  query: "How long does delivery take?",
  locale: "en",
  clientId: "visitor_12345678",
});

if (result.kind === "answer") {
  console.log(result.answer, result.sources);
}

search liefert Datensätze mit _id, question, answer und optional group und url. ask liefert answer, abstain oder unavailable. Zeigen Sie die Quellen zusammen mit der Antwort an. Behandeln Sie die anderen Ergebnisse, ohne eine Antwort zu erfinden. Die Komponente unterstützt en, fr, de, es und it. Ersetzen Sie locale: "en" durch locale: "de" für eine deutsche Anfrage.

Anfragen enthalten 2 bis 200 Zeichen. Die Suche akzeptiert ein Limit von 1 bis 20 Ergebnissen. Verwenden Sie eine stabile clientId mit 8 bis 200 Zeichen aus Buchstaben, Ziffern, Punkten, Unterstrichen, Doppelpunkten oder Bindestrichen. Die Kennung im Beispiel dient der Veranschaulichung. Übergeben Sie die Kennung, die Ihre Anwendung dem Aufrufer zuweist.

Prüfen Sie die Berechtigungen Ihrer Host-Funktionen, bevor Sie diese Clients zugänglich machen. Für KI-Antworten gelten weiterhin der Tarif, das monatliche Kontingent und die Ratenbegrenzungen des Askolia-Projekts.

Innerhalb Ihrer Mutations synchronisieren

Speichern Sie beim Anlegen eines Artikels den Datensatz und den Synchronisierungsauftrag in derselben Mutation. title und content sind hier die Artikelfelder, die Ihre Mutation entgegennimmt:

const id = await ctx.db.insert("articles", { title, content });
const revision = await askolia.syncDocument(ctx, {
  key: id,
  title,
  content,
});

Verwenden Sie denselben stabilen Schlüssel für spätere Aktualisierungen. Schlägt die Mutation fehl, werden Datenbankänderung, Auftrag und geplanter Worker gemeinsam zurückgerollt. Die Übertragung an Askolia erfolgt nach dem Commit. Die Systeme sind daher nicht sofort auf demselben Stand.

Erfassen Sie in der Mutation, die den Artikel löscht, auch dessen Entfernung:

await ctx.db.delete(articleId);
await askolia.removeDocument(ctx, { key: articleId });

Synchronisieren Sie ausschliesslich Inhalte für die öffentliche Suche. Die Dokumente ergänzen das veröffentlichte Wissen des Askolia-Projekts und können in der öffentlichen Suche und in KI-Antworten erscheinen. V1 synchronisiert weder Berechtigungen noch private Nutzerdaten.

Die Übertragung verfolgen und Fehler erneut versuchen

Stellen Sie eine reaktive Query Ihrer Anwendung mit Berechtigungsprüfung bereit, die Folgendes aufruft:

const state = await askolia.getSyncState(ctx, { key: articleId });

Vor dem ersten Auftrag liefert sie null. Prüfen Sie danach revision und status gemeinsam. Mögliche Statuswerte sind pending, syncing, synced und failed. Der Zustand enthält auch die Anzahl der Versuche, den nächsten geplanten Versuch und gegebenenfalls eine von sensiblen Daten bereinigte Fehlermeldung. synced bedeutet, dass Askolia die Dokumentänderung bestätigt hat. Es bedeutet nicht, dass Embeddings oder KI-Antworten bereits verfügbar sind. Metadaten eines früheren Erfolgs können bestehen bleiben, während eine neuere Revision noch aussteht.

Netzwerkfehler sowie HTTP 408 und 5xx lösen bis zu acht Versuche aus. Die Wartezeit beginnt bei fünf Sekunden und verdoppelt sich bis auf fünf Minuten. HTTP 429 führt zu einer Wartezeit von 60 bis 75 Sekunden, ohne das Versuchslimit zu verbrauchen. Andere HTTP-Fehler stoppen sofort. Eine zeitlich begrenzte Sperre und ein geplanter Watchdog übernehmen unterbrochene Worker.

Rufen Sie nach der Korrektur von Zugangsdaten oder Übertragungsproblemen askolia.retrySync(ctx, { key: articleId }) aus einer Mutation auf. Dies wiederholt dieselbe Revision mit einem neuen Versuchslimit. Verwenden Sie für korrigierte Inhalte stattdessen syncDocument. Eine autorisierte Query kann mit listFailed und paginationOpts Fehler in Seiten mit höchstens zehn Zuständen abrufen.

Namespaces und die Grenzen von V1

Jede Komponenteninstanz hat einen persistenten Namespace. Derselbe Dokumentenschlüssel in einem anderen Namespace bezeichnet ein anderes Dokument. Steigende Revisionen, idempotente Wiederholungen und gespeicherte Löschmarkierungen verhindern, dass eine verspätete ältere Änderung gelöschte Inhalte wiederherstellt. Eine Neuinstallation mit neuem Namespace übernimmt oder entfernt die Dokumente der vorherigen Instanz nicht.

Namespaces trennen Dokumentidentitäten. Innerhalb eines Askolia-Projekts erzeugen sie keine getrennten öffentlichen Suchsammlungen. Alle Namespaces mit Schlüsseln dieses Projekts tragen zu dessen öffentlichem Wissen und Zuordnungslimit bei. Das Löschen eines Preview-Deployments oder das Widerrufen seines Schlüssels entfernt keine Dokumente und gibt keine Zuordnungen frei.

Berücksichtigen Sie vor der Integration diese Grenzen:

Dokumente enthalten Text oder Markdown, einen Titel mit 1 bis 200 Zeichen und Inhalt mit 1 bis 100 000 UTF-8-Bytes. Schlüssel dürfen nicht leer sein und sind auf 200 Zeichen begrenzt. V1 bietet weder PDF-Extraktion noch beliebige Datei-Uploads.
Synchronisierte Dokumente nennen den Titel als Quelle, haben in dieser Version aber keine Quell-URL.
ask verarbeitet eine Frage pro Aufruf. Es erstellt keine Supportkonversation und führt keinen Gesprächsverlauf.
Die Synchronisierung läuft von Ihrer Anwendung zu Askolia. Dashboard-Änderungen fliessen nicht zurück. Eine neue Revision kann den Inhalt Ihrer Anwendung erneut veröffentlichen; eine exakte Wiederholung behält die ursprüngliche Bestätigung bei.
Jede Instanz akzeptiert 2 000 verschiedene Schlüssel einschliesslich Löschmarkierungen. Löschen gibt keinen Platz frei. Es gibt weder automatische Bereinigung noch ein Zurücksetzen des Namespace.
Der Server akzeptiert 2 000 Dokumentzuordnungen und zehn aktive API-Schlüssel pro Projekt. Das separate gemeinsame Limit von 500 Dokumenten gilt weiterhin. Suche und ask teilen sich 120 Anfragen pro Minute; Dokumentänderungen haben ein eigenes Limit von 120 Anfragen pro Minute.

Beginnen Sie mit einem isolierten Entwicklungsprojekt und wenigen öffentlichen Dokumenten. Prüfen Sie Übertragungsstatus, Suchergebnisse und Antwortquellen, bevor Sie Produktionsinhalte anbinden. Die README des Pakets beschreibt Konfiguration, Validierung, Fehlerbehebung und die Testhilfe. Die Convex-Komponentendokumentation erklärt die Einbindung in eine Convex-Anwendung.