Ollama vorbereiten
Installiere Ollama nach der offiziellen Anleitung. Starte die Ollama-Anwendung oder bei einer Kommandozeileninstallation ollama serve in einem eigenen Terminal. Läuft der Dienst bereits, verwende diesen weiter.
Lade ein Modell für Texteinbettungen herunter:
ollama pull embeddinggemmaPrüfe den OpenAI-kompatiblen Endpunkt, den FACET verwenden wird. Diese direkte HTTP-Anfrage braucht keinen Platzhalter-Schlüssel:
curl http://localhost:11434/v1/embeddings \ -H 'Content-Type: application/json' \ -d '{"model":"embeddinggemma","input":"Ein abgelaufener Rabattcode muss abgelehnt werden."}'
Erwartet wird eine JSON-Antwort mit data und einem embedding-Array. Die Zahlen hängen vom Modell ab. Kläre einen Endpunktfehler, bevor du das Projekt indexierst.
FACET verbinden
Öffne die vorhandene .facetrc.yaml des Projekts und ergänze diesen Block auf oberster Ebene. Bestehende Registry- und Projekteinstellungen bleiben erhalten:
embedding: provider: openai base_url: http://localhost:11434/v1 model: embeddinggemma
openai wählt hier das kompatible HTTP-Anfrageformat. Es bedeutet nicht, dass die Anfrage an OpenAI geht. FACET hängt /embeddings an base_url an. Verwende für diese Konfiguration nicht Ollamas separaten Endpunkt /api/embed.
Lasse api_key_env für gewöhnliches lokales Ollama weg. Ist die Einstellung noch für einen anderen Anbieter gesetzt, entferne sie für diese lokale Konfiguration. Die lokale API benötigt keine Anmeldung. Manche SDK-Beispiele verwenden ollama als Blindwert, weil das SDK einen Schlüssel verlangt; FACETs HTTP-Client verlangt ihn nicht.
FACETs provider: local bezeichnet die eingebaute Suche nach Wortüberschneidungen, nicht Ollama. Der Block oben wählt bewusst einen HTTP-Endpunkt mit Einbettungsmodell.
Index bauen und suchen
Führe diese Befehle im Projektordner aus. Der Indexlauf schreibt Suchdaten; beim Standardlayout liegen sie unter docs/facets/generated.rag.bin. Ein Projekt kann einen anderen Indexpfad konfigurieren. Der Index enthält aus Projekttexten abgeleitete Daten. Beachte deshalb die Regeln deines Projekts für Ablage und Weitergabe.
facet rag indexfacet rag query "Was passiert, wenn ein Kunde einen abgelaufenen Rabattcode verwendet?" --limit 5
Der erste Befehl liest Records und erzeugte Dokumente, die FACETs Erzeugungsmanifest erfasst. Er indexiert nicht jede beliebige Datei im Repository. Der zweite liefert sortierte Textstellen mit Quellpfaden und Ähnlichkeitswerten. Ein solcher Wert ist keine Wahrscheinlichkeit für eine richtige Antwort.
Öffne die gefundenen Dateien. Lies Bedingungen und Ausnahmen, bevor du etwa schließt, dass ein abgelaufener Code abgelehnt wird. Beantworten die Records die Frage nicht, benenne die fehlenden Informationen.
Erstelle den Index nach Änderungen an den betroffenen Records oder Dokumenten neu. Baue ihn auch bei einem Modellwechsel neu: Indexierung und Suche müssen dasselbe Einbettungsmodell verwenden.
Mit einem Agenten arbeiten
Formuliere die Frage und die erwarteten Belege ausdrücklich:
Finde das dokumentierte Verhalten für abgelaufene Rabattcodes in diesem Projekt.Nutze die FACET-Suche, falls verfügbar. Lies passende Records und ihre Szenarien.Nenne die Quelldateien und unterscheide dokumentierte Versprechen von bestandenen Tests.Wenn die Quellen die Frage nicht beantworten, benenne die Lücke, statt zu raten.
Ist deine Agentenanwendung mit dem facet mcp-Server des Projekts verbunden, bietet FACET das Werkzeug rag_query an. Das folgende Beispiel zeigt Werkzeugname und Argumente. Es ist kein Shell-Befehl und kein Nachweis einer bereits eingerichteten Verbindung:
{ "tool": "rag_query", "arguments": { "query": "Was passiert, wenn ein Kunde einen abgelaufenen Rabattcode verwendet?", "limit": 5, "kind": "record" }}
Die Antwort enthält Quellpfade und Text. Kennt der Agent die Feature-Id, kann er anschließend das Serverwerkzeug feature_get verwenden. Der Client kann Werkzeugnamen einen eigenen Präfix voranstellen. Der MCP-Prozess muss im selben konfigurierten Projekt laufen und gegebenenfalls die Umgebungsvariablen des Einbettungsendpunkts erhalten.
Ohne diese MCP-Verbindung kann ein Agent mit Shell-Berechtigung Folgendes ausführen:
facet rag query "Was passiert, wenn ein Kunde einen abgelaufenen Rabattcode verwendet?" --limit 5 --jsonFehlt der Suchindex, hilft auch eine direkte Textsuche:
rg -n -i 'abgelaufen|Rabatt|Gutschein' docs/facetsrg ist ein eigenes Kommandozeilenwerkzeug. Es sucht Wörter statt Bedeutung. Passe Suchbegriffe und Verzeichnis an Sprache und Ablage deines Projekts an. Mensch oder Agent müssen die gefundenen Dateien weiterhin lesen.
Schlüssel richtig einordnen
Für die lokale Einrichtung oben musst du keinen Token beschaffen, erzeugen oder irgendwo einfügen.
Verwendet eure Organisation einen OpenAI-kompatiblen Endpunkt hinter einem Proxy mit Bearer-Token, stellt dessen Betreiber den Token bereit. Einen Ollama-Cloud-Schlüssel erhältst du in den API-Schlüssel-Einstellungen deines Ollama-Kontos. Dieser ist nicht automatisch ein Zugangsschlüssel für euren eigenen Proxy. Diese Anleitung nutzt weder Cloud-Inferenz noch einen geschützten Proxy.
Für einen solchen separat eingerichteten Endpunkt unterstützt FACET:
embedding: provider: openai base_url: https://embeddings.example.invalid/v1 model: your-approved-embedding-model api_key_env: FACET_EMBEDDING_TOKEN
Hostname und Modell sind Platzhalter, kein funktionierender Dienst. Ersetze sie nur durch die Angaben des Endpunktbetreibers. Setze FACET_EMBEDDING_TOKEN über eure übliche Geheimnisverwaltung in der Umgebung des FACET-Prozesses. FACET liest die Variable und sendet Authorization: Bearer ... nur bei einem nicht leeren Schlüssel. Es erzeugt oder beschafft den Token nicht selbst. Andere Anmeldeverfahren lassen sich mit diesem Feld nicht konfigurieren.
Wenn etwas nicht passt
- Verbindung abgelehnt: Starte den lokalen Ollama-Dienst auf dem Rechner, auf dem FACET läuft. In Containern oder Fernsitzungen bezeichnet
localhostdiese Umgebung, nicht unbedingt deinen Desktop. - Modell nicht gefunden: Prüfe den Namen und schließe
ollama pull embeddinggemmaab. - 404 oder unerwartete Antwort: Verwende die API-Basis
http://localhost:11434/v1. FACET ergänzt/embeddingsselbst. - Keine Records zum Indexieren: Wechsle in das Projekt mit den Records oder verwende FACETs globale Option
--root. Diese Anleitung legt keine Records an und dokumentiert keine Codebasis nach. - Kein Index: Führe zuerst
facet rag indexmit derselben Projektkonfiguration aus. - Suche nur nach Wortüberschneidungen: Prüfe
embedding.provider: openaiund baue den Index mit dem konfigurierten Modell neu. Der eingebaute Anbieterlocalarbeitet lexikalisch. - 401 an einem geschützten Endpunkt: Prüfe dessen Zugangsanforderungen und die Prozessumgebung. Füge bei gewöhnlichem lokalem Ollama keinen Schlüssel ein, nur um ein SDK-Beispiel nachzuahmen.