KI einrichten

Einrichtung und Konfiguration

Lesen Sie vor jedem Schritt Bevor Sie beginnen und Terminal-Grundlagen. Bei diesen Anweisungen wird davon ausgegangen, dass Sie das vollständige Supastack-Monorepo in VS Code geöffnet haben. Sein Stamm package.json markiert den Repository-Stamm. In pnpm-Befehlen ist ein Arbeitsbereichspaket eine App oder ein Ordner mit gemeinsam genutztem Code. Im Produkt ist ein Arbeitsbereich der Datencontainer und die Sicherheitsgrenze eines Teams. corepack pnpm --filter ... wählt ein Paket aus dem Monorepo aus, während Befehle von seinem Stammverzeichnis aus ausgeführt werden. Wenn Sie nur einen synchronisierten Mobil- oder Desktop-Ordner geöffnet haben, enthält dieser weder das Web-Backend, Docker-Setup noch Root-Skripte: Führen Sie das Backend von diesem Monorepo oder einem erreichbaren gehosteten Server aus und verwenden Sie die eigenen Skripte des Plattformordners. Eine Umgebungsvariable ist eine benannte Einstellung, die in einer lokalen .env-Datei oder Ihrem Hosting-Dashboard gespeichert ist; Starten Sie die entsprechende App neu, nachdem Sie sie geändert haben, und halten Sie Servergeheimnisse von den Werten NEXT_PUBLIC_ und EXPO_PUBLIC_ fern.

1. Öffnen Sie apps/web/.env.local für den lokalen Webserver und apps/web/src/agent-runtime.ts für die Anbieterauswahl. .env.example ist die Liste der unterstützten Einstellungsnamen.

2. Behalten Sie AI_PROVIDER=fake für die lokale Schnittstellenarbeit bei, es sei denn, Sie verfügen über ein eigenes Anbieterkonto und möchten die echte Generierung testen. Legen Sie niemals Anbieterschlüssel in einer NEXT_PUBLIC_- oder EXPO_PUBLIC_-Einstellung ab.

3. Starten Sie die Web-App im Repository-Stammverzeichnis mit corepack pnpm --filter @supastack/web dev. Erwartet: Lokale Bildschirme können erkundet werden, ohne einen kostenpflichtigen Anbieter zu konfigurieren. Für die tatsächliche Generierung sind ein gültiger Serveranbieter und aktivierte Modelloptionen im Datenbankkatalog erforderlich.

Der Standardwert AI_PROVIDER=fake unterstützt deterministische lokale Arbeit. Echte Provider werden in der Serverumgebung konfiguriert. Die in .env.example aufgeführten Provider-Schlüssel decken OpenAI, Anthropic und einen OpenAI-kompatiblen Endpunkt ab.

AI_MODEL_POLICY enthält geordnete Modell-IDs für die Aliase cheap, fast und smart. Eine leere Aliasliste deaktiviert diese Auswahl. Modell-IDs müssen aktivierten Katalogeinträgen in der Datenbank mit gültigen, unveränderlichen Preisen entsprechen.

AI_MODEL_POLICY='{"cheap":[],"fast":["catalog-model-id"],"smart":["catalog-model-id"]}'
AGENT_FRAMEWORK=ai-sdk    # ai-sdk | mastra | langgraph | openai-agents

Befehle zum Kopieren

Befolgen Sie die Kommentare, um zu sehen, in welchem Ordner ein Befehl ausgeführt wird. Wenn zwei Terminals gekennzeichnet sind, öffnen Sie zwei Terminalfenster und lassen Sie den ersten Befehl laufen, während Sie den zweiten verwenden.

corepack pnpm --filter @supastack/web dev

Implementierungsablauf

Konfigurieren Sie Katalog und Workspace-Richtlinie, bevor Sie Produktionsaufgaben annehmen. Der Browser erhält die aktivierten Aliase; Funktionsabgleich, Modellauswahl, Berechtigungsprüfung und Budgetkontrolle bleiben auf dem Server.

Legen Sie Zugangsdaten niemals in Variablen mit NEXT_PUBLIC_ oder EXPO_PUBLIC_ ab. Verwenden Sie für eigene Schlüssel die bestehende verschlüsselte Hülle und serverseitige Entschlüsselungsgrenze; geben Sie niemals einen gespeicherten Providerschlüssel an die Oberfläche zurück.

Überprüfung und Fehlerbehebung

Meldet die App, dass kein KI-Modell verfügbar ist, prüfen Sie AI_PROVIDER auf dem Server, aktivierte Modelle und Preise im Admin-Katalog sowie die Alias-Richtlinie cheap/fast/smart. Liefert ein echter Anbieter einen Authentifizierungsfehler, prüfen Sie seinen Schlüssel in apps/web/.env.local und starten Sie den Server neu. Ein Schlüssel mit dem Präfix NEXT_PUBLIC_ wäre im Browser sichtbar und muss entfernt werden.

Prüfen Sie deaktivierte Aliase, fehlende Funktionen, inaktive Berechtigungen und ausgeschöpfte Budgets. Verwenden Sie für echte Generierung einen separat autorisierten Provider-Smoke-Test. Ist kein Alias verfügbar, prüfen Sie die Serverrichtlinie und den Katalog, statt einen freien Modellwähler anzuzeigen.