- Was ein Code-Interpreter zu einer KI-App beiträgt
- Referenzarchitektur
- Implementierungsablauf
- Dateien, Ausgaben und generierte Artefakte verwalten
- Paket- und Netzwerkrichtlinie festlegen
- Limits, Protokolle, Bereinigung und Überprüfung anwenden
- Wo Novita Agent Sandbox passt
- Evaluierungs-Checkliste
- Fazit
- FAQ
- Empfohlene Artikel
Fügen Sie einen Code-Interpreter zu einer KI-App hinzu, indem Sie die vom Modell angeforderte Code-Ausführung in eine isolierte Sandbox mit abgegrenzten Dateien, einer klaren Paketrichtlinie, Ressourcen- und Zeitlimits, erfassten Ausgaben und einer anwendungsseitigen Überprüfung leiten, bevor Ergebnisse angezeigt oder gespeichert werden. Das Modell kann entscheiden, wann Code nützlich ist, aber Ihre App sollte die Ausführungsgrenze kontrollieren: Laden Sie nur die für die Aufgabe benötigten Dateien hoch, erstellen oder verwenden Sie eine kurzlebige Sandbox-Sitzung, führen Sie Python mit strengen Limits aus, erfassen Sie stdout, stderr, generierte Dateien und Protokolle, geben Sie ein strukturiertes Ergebnis an das Modell zurück und räumen Sie die Sitzung auf, wenn der Workflow abgeschlossen ist.
Was ein Code-Interpreter zu einer KI-App beiträgt
Ein Code-Interpreter verwandelt ein Sprachmodell von einem rein textbasierten Assistenten in eine werkzeugnutzende Anwendung, die berechnen, Dateien transformieren, Daten inspizieren, Diagramme erstellen und überprüfbare Artefakte produzieren kann. Anstatt das Modell zu bitten, aus einem Prompt heraus über eine Tabelle zu argumentieren, kann die App dem Modell erlauben, Python zu schreiben, es gegen die hochgeladene Datei auszuführen, die Ausgabe zu inspizieren und das Ergebnis zu erklären.
Das nützliche Muster ist nicht „das Modell alles ausführen lassen“. Das nützliche Muster ist kontrollierte Ausführung. Ihre Anwendung akzeptiert eine Benutzeraufgabe, lässt das Modell einen Tool-Aufruf wie run_python anfordern und führt diese Anfrage dann innerhalb einer Sandbox aus, anstatt im Hauptanwendungsprozess. Die Sandbox wird zur Werkbank für temporäre Dateien, Paketinstallationen, Skripte, Diagramme und Protokolle.
Code-Interpreter-Funktionen sind besonders nützlich für:
- CSV-, Excel-, JSON- und Log-Analyse
- Diagrammerstellung aus hochgeladenen Daten
- Formatkonvertierung und Datenbereinigung
- Mathematik- und Simulationsaufgaben, die exakte Berechnungen erfordern
- Code-Schnipsel, die getestet werden müssen, bevor das Modell sie erklärt
- mehrschrittige Agent-Workflows, bei denen Ausgaben eines Schritts zu Eingaben für den nächsten werden
Sie sind ungeeignet für Aufgaben, die uneingeschränkte Produktionsanmeldeinformationen, langlebigen Zugriff auf private Systeme oder stille Ausführung ohne sichtbaren Prüfpfad für den Benutzer erfordern. Wenn das Ergebnis Geld, Infrastruktur, Sicherheit oder Zugriffskontrolle beeinflussen kann, fügen Sie Überprüfungs-Gates ein, bevor ein Nebeneffekt die Sandbox verlässt.
Referenzarchitektur
Eine praktische Code-Interpreter-Architektur besteht aus fünf Teilen:
| Ebene | Verantwortung | Übliches Design |
|---|---|---|
| Benutzeroberfläche | Dateien hochladen, Fortschritt anzeigen, Artefakte darstellen, Genehmigung anfordern | Hochgeladene Dateien auf die aktuelle Konversation oder das Projekt beschränken |
| Anwendungsserver | Benutzer authentifizieren, Richtlinien durchsetzen, Sandbox-Sitzungen erstellen, Protokolle speichern | Rohdaten der Sandbox-Anmeldeinformationen niemals dem Browser aussetzen |
| Modell-Orchestrierung | Entscheiden, wann Code-Tools aufgerufen werden, und Ergebnisse zusammenfassen | Strukturierte Tool-Aufrufe verwenden, anstatt Freitext zu parsen |
| Sandbox-Laufzeit | Python ausführen, temporäre Dateien halten, erlaubte Pakete installieren | Mit Ressourcen-, Timeout- und Bereinigungssteuerungen ausführen |
| Artefakt-Speicher | Genehmigte Ausgaben wie Diagramme, CSVs, Berichte und Protokolle aufbewahren | Nur Ausgaben speichern, die die App oder der Benutzer akzeptiert hat |
Das Modell sollte nicht direkt die Infrastruktur kontrollieren. Es sollte einen Tool-Aufruf anfordern. Ihre Anwendung entscheidet, ob dieser Tool-Aufruf erlaubt ist, welche Dateien angehängt sind, wie lange er laufen darf, welche Pakete verfügbar sind und welche Ausgaben zurückgegeben werden.
Diese Trennung hält das Modell nützlich, ohne es zur Sicherheitsgrenze zu machen.
Implementierungsablauf
Ein solider Implementierungsablauf beginnt, bevor überhaupt Code ausgeführt wird.
1. Benutzeraufgabe und Dateien annehmen
Wenn der Benutzer eine Datei hochlädt, speichern Sie sie unter einem anwendungsbezogenen Dateidatensatz mit Eigentümer, Arbeitsbereich, Inhaltstyp, Größe und Aufbewahrungsrichtlinie. Legen Sie nicht sofort jede Datei im Benutzerkonto dem Interpreter offen. Die Sandbox sollte nur die Dateien erhalten, die für die aktuelle Aufgabe benötigt werden.
Ein Benutzer könnte zum Beispiel fragen:
„Analysiere diese CSV, finde die wichtigsten Umsatztreiber und gib ein Diagramm plus eine kurze Erklärung zurück.“
Ihre App kann die hochgeladene CSV für die nächste Modellrunde als verfügbare Datei anhängen, aber die eigentlichen Dateibytes sollten erst dann in die Sandbox verschoben werden, wenn die Code-Ausführung genehmigt ist.
2. Das Modell einen Tool-Aufruf anfordern lassen
Definieren Sie eine schmale Tool-Oberfläche. Eine typische erste Version benötigt nur wenige Tools:
{
"name": "run_python",
"arguments": {
"code": "import pandas as pd\n...",
"input_files": ["sales.csv"],
"expected_outputs": ["summary.json", "revenue_chart.png"],
"timeout_seconds": 30
}
}
Halten Sie das Schema explizit. Das Modell sollte den Code, die Eingabedateien, die erwarteten Ausgaben und eine Timeout-Anfrage deklarieren. Die Anwendung kann das Timeout verkürzen, unbekannte Dateien ablehnen oder Befehle blockieren, die gegen die Richtlinie verstoßen.
3. Eine Sandbox-Sitzung erstellen oder wiederverwenden
Erstellen Sie für eine einmalige Assistentenantwort eine neue Sandbox-Sitzung, laden Sie die Eingabedateien hoch, führen Sie den Code aus, sammeln Sie das Ergebnis und beenden Sie die Sitzung. Für eine notebookähnliche Benutzererfahrung halten Sie eine Sitzung für die aktuelle Konversation am Leben, damit spätere Zellen frühere Variablen und Dateien wiederverwenden können.
Kurzlebige Sitzungen sind einfacher zu durchschauen. Zustandsbehaftete Sitzungen sind ergonomischer für Analyseaufgaben. Wählen Sie bewusst und zeigen Sie dem Benutzer an, wann ein Zustand existiert.
4. Python ausführen und Ergebnisse erfassen
Führen Sie Code über die Sandbox-Ausführungs-API oder Ihren eigenen Worker innerhalb der Sandbox aus. Erfassen Sie strukturierte Ausführungsausgaben:
{
"status": "success",
"stdout": "Loaded 12,448 rows\n",
"stderr": "",
"artifacts": [
{
"path": "revenue_chart.png",
"type": "image/png",
"size_bytes": 84231
},
{
"path": "summary.json",
"type": "application/json",
"size_bytes": 1260
}
],
"duration_ms": 1840
}
Geben Sie dieses strukturierte Ergebnis an das Modell zurück. Das Modell kann dann erklären, was passiert ist, auf die generierten Dateien verweisen und fragen, ob der Benutzer einen weiteren Durchlauf wünscht.
5. Ergebnisse dem Benutzer zurückgeben
Zwingen Sie den Benutzer nicht, Rohprotokolle zu lesen, es sei denn, etwas ist fehlgeschlagen. Eine gute Oberfläche zeigt die Antwort, das generierte Diagramm oder die Datei und einen kleinen Hinweis, dass Code ausgeführt wurde. Bieten Sie ein erweiterbares Ausführungsprotokoll zur Überprüfung an.
Zeigen Sie bei fehlgeschlagenen Ausführungen einen präzisen Fehler an und lassen Sie das Modell den Code überarbeiten. Vermeiden Sie es, lange Tracebacks in den Haupt-Chat zu werfen, es sei denn, der Benutzer debuggt.
Dateien, Ausgaben und generierte Artefakte verwalten
Die Dateiverwaltung ist der Bereich, in dem viele Code-Interpreter-Projekte unübersichtlich werden. Behandeln Sie Eingaben und Ausgaben als separate Objekte.
Eingabedateien sollten unter stabilen, bereinigten Pfaden in die Sandbox kopiert werden. Vermeiden Sie es, vom Benutzer bereitgestellte Pfadnamen zu erhalten, die Leerzeichen, Shell-Zeichen oder verschachtelte Verzeichnisse enthalten. Führen Sie eine Zuordnung von Anzeigename zu Sandbox-Pfad im Anwendungszustand.
Generierte Dateien sollten gescannt und klassifiziert werden, bevor sie zu herunterladbaren Artefakten werden. Ein Diagrammbild, eine bereinigte CSV, eine JSON-Zusammenfassung oder ein PDF-Bericht sind möglicherweise sicher direkt darstellbar. Ein generiertes Skript, eine ausführbare Datei oder ein Archiv erfordert eine strengere Handhabung.
Bitten Sie das Modell bei der Diagrammerstellung, Bilddateien explizit zu speichern, anstatt sich nur auf die Inline-Anzeige zu verlassen. Bitten Sie bei der Datenanalyse um eine maschinenlesbare Zusammenfassungsdatei sowie um eine Erklärung in natürlicher Sprache. Das gibt Ihrer App etwas Stabiles zum Validieren und Speichern.
Eine nützliche Artefaktrichtlinie sieht so aus:
| Artefakttyp | Standardbehandlung |
|---|---|
.png, .jpg, .webp, .svg Diagramme |
In der UI nach Größen- und Typenprüfung in der Vorschau anzeigen |
.csv, .json, .xlsx Datenausgaben |
Als Downloads anbieten und Änderungen zusammenfassen |
.txt, .md, .pdf Berichte |
Je nach Größe als Vorschau anzeigen oder herunterladen |
.py, .sh, Binärdateien, Archive |
Nicht automatisch ausführen oder öffnen; explizite Überprüfung erforderlich |
Wenn Ihre App persistente Projekte unterstützt, speichern Sie akzeptierte Artefakte außerhalb der Sandbox. Die Sandbox sollte wegwerfbar bleiben.
Paket- und Netzwerkrichtlinie festlegen
Die meisten Code-Interpreter-Workflows benötigen Pakete wie pandas, NumPy, matplotlib, seaborn, scikit-learn oder openpyxl. Die Frage ist, ob Pakete vorinstalliert, bei Bedarf installiert oder in benutzerdefinierte Sandbox-Vorlagen eingebaut werden.
Vorinstallierte Pakete halten die Ausführung vorhersagbar. Installationen bei Bedarf sind flexibel, können aber Aufgaben verlangsamen und Abweichungen bei den Abhängigkeiten einführen. Benutzerdefinierte Vorlagen sind in der Regel der beste Produktionsweg, sobald Sie Ihre üblichen Workloads kennen.
Legen Sie vor dem Start eine Paketrichtlinie fest:
- welche Pakete immer verfügbar sind
- ob das Modell Paketinstallationen anfordern darf
- ob Installationen öffentliche Paketindizes erreichen können
- ob Versionsfestlegungen erforderlich sind
- wie lange Installationen laufen dürfen
- ob kompilierte oder native Pakete erlaubt sind
Die Netzwerkrichtlinie ist genauso wichtig. Viele Datenaufgaben benötigen nach dem Hochladen der Dateien keinen Internetzugang. Wenn ein Workflow externe APIs benötigt, leiten Sie Anmeldeinformationen über anwendungsgenehmigte Tools weiter, anstatt breite Geheimnisse in die Sandbox zu werfen. Das Modell sollte standardmäßig keine uneingeschränkten Umgebungsvariablen erhalten.
Limits, Protokolle, Bereinigung und Überprüfung anwenden
Ein Code-Interpreter ist eine Produktionsfunktion, kein Demo-Zellen-Ausführer. Setzen Sie von Anfang an Limits darum.
Zu den Mindestkontrollen sollten gehören:
- maximale Ausführungszeit pro Zelle oder Tool-Aufruf
- maximale Ausgabegröße für stdout und stderr
- maximale Artefaktgröße und Dateianzahl
- CPU- und Speicherlimits, die für die Aufgabe angemessen sind
- erlaubte Dateierweiterungen für Vorschau und Download
- Nebenläufigkeitslimits pro Benutzer und pro Arbeitsbereich
- Bereinigungsregeln für temporäre Sitzungen und Dateien
Protokolle sollten drei Fragen beantworten: Wer hat die Ausführung angefordert, welcher Code wurde ausgeführt und welche Ausgaben wurden produziert? Speichern Sie genug, um den Workflow zu debuggen und zu prüfen, aber vermeiden Sie es, private hochgeladene Daten länger aufzubewahren, als es Ihre Produktrichtlinie vorschreibt.
Die menschliche oder Benutzerüberprüfung ist die letzte Kontrolle. Für risikoarme Analysen kann die Überprüfung bedeuten, dass der Benutzer das Diagramm sieht, bevor er es herunterlädt. Für Agent-Workflows, die Tickets aktualisieren, in Datenbanken schreiben oder externe APIs aufrufen können, sollte die Überprüfung vor dem Nebeneffekt erfolgen, nicht danach.
Wo Novita Agent Sandbox passt
Novita Agent Sandbox ist für KI-Agenten konzipiert, die isolierte Laufzeitumgebungen für Code-Ausführung, Browser-Workflows, Aufgaben im Computer-Use-Stil, Evaluierungen, Umgebungen für verstärkendes Lernen und langlaufende Workflows benötigen. Für eine Code-Interpreter-Funktion bedeutet dies, dass die Sandbox als Ausführungsschicht dienen kann, während Ihre App für Benutzerauthentifizierung, Modell-Orchestrierung, Dateirichtlinie, Überprüfung und produktspezifische Aufbewahrung verantwortlich bleibt.
Die Novita-Sandbox-Dokumentation umfasst Dateisystem-Workflows zum Lesen, Schreiben, Hochladen, Herunterladen und Überwachen von Dateien in einer Sandbox. Diese Fähigkeiten lassen sich direkt auf die Bedürfnisse von Code-Interpretern abbilden: Benutzerdateien in die Ausführungsumgebung verschieben, Code Diagramme oder transformierte Daten generieren lassen und dann ausgewählte Ausgaben zurück in die App bringen. Siehe die Novita Sandbox-Dokumentation zum Dateisystem für den aktuellen Überblick über Dateioperationen.
Wenn Ihr Interpreter über einen einfachen Python-Ausführer hinauswächst, können benutzerdefinierte Sandbox-Vorlagen helfen, Abhängigkeiten und Laufzeit-Setup zu standardisieren. Das ist nützlich, wenn jede Sitzung denselben Analyse-Stack, interne Befehlszeilen-Tools oder projektspezifische Bibliotheken benötigt. Beginnen Sie mit einem kleinen, erlaubten Paketsatz und verschieben Sie wiederholtes Setup in Vorlagen, sobald sich die Workload stabilisiert.
Halten Sie Novita-spezifische Integrationsentscheidungen von der allgemeinen Architektur getrennt. Ihr Code-Interpreter benötigt weiterhin anwendungsbezogene Richtlinien für Dateisichtbarkeit, Paketinstallation, Netzwerkzugriff, Protokollaufbewahrung und Überprüfung. Die Sandbox stellt die kontrollierte Laufzeit bereit; Ihr Produkt definiert, wie diese Laufzeit verwendet wird.
Evaluierungs-Checkliste
Testen Sie die Funktion vor der Auslieferung mit echten Workloads und adversarischen Prompts.
| Frage | Was zu überprüfen ist |
|---|---|
| Können Benutzer die richtigen Dateien hochladen? | Dateigröße, Typenprüfungen, Eigentümerprüfungen und klare Fehlermeldungen |
| Kann das Modell sauber eine Ausführung anfordern? | Strukturierte Tool-Aufrufe mit Code, Eingaben, erwarteten Ausgaben und Timeout |
| Ist die Sandbox korrekt abgegrenzt? | Nur genehmigte Dateien und Umgebungsvariablen sind verfügbar |
| Sind Pakete vorhersagbar? | Gängige Pakete funktionieren, verbotene Pakete schlagen klar fehl, Installationen haben Limits |
| Sind Ausgaben nutzbar? | Diagramme werden gerendert, Dateien werden heruntergeladen, Zusammenfassungen stimmen mit generierten Artefakten überein |
| Sind Fehler behebbar? | Tracebacks werden erfasst, das Modell kann Code überarbeiten, Benutzer sehen präzise Fehler |
| Werden Limits durchgesetzt? | Endlosschleifen, riesige Ausgaben, speicherintensive Aufgaben und lange Installationen werden beendet |
| Ist die Überprüfung eingebaut? | Benutzer können Code, Protokolle und Artefakte vor wichtigen Nebeneffekten inspizieren |
| Ist die Bereinigung zuverlässig? | Temporäre Dateien und Sitzungen werden planmäßig entfernt oder ablaufen gelassen |
Die beste erste Veröffentlichung ist normalerweise schmal: Python-Ausführung, ein kleiner Paketsatz, Datei-Upload, Diagramme und herunterladbare Dateien, klare Limits und ein Ausführungsprotokoll. Fügen Sie breitere Paketinstallationen, persistente Sitzungen, externen API-Zugriff und agentische Nebeneffekte erst hinzu, nachdem die grundlegende Schleife beobachtbar und zuverlässig ist.
Fazit
Ein Code-Interpreter funktioniert am besten, wenn das Modell eine Ausführung anfordern kann, aber Ihre App die Sandbox, Dateien, Limits und den Überprüfungsschritt kontrolliert. Beginnen Sie mit einem schmalen Python-Tool, halten Sie Ein- und Ausgaben explizit und erweitern Sie erst, nachdem der Ablauf stabil ist.
FAQ
Was ist der sicherste Weg, einen Code-Interpreter hinzuzufügen?
Verwenden Sie eine isolierte Sandbox, grenzen Sie die Eingabedateien ein, begrenzen Sie Laufzeit und Speicher und geben Sie strukturierte Ausgaben anstelle von rohem Shell-Zugriff zurück.
Sollte das Modell Paketinstallationen kontrollieren?
Nur innerhalb einer von Ihnen definierten Richtlinie. Viele Apps beginnen mit einem festen Paketsatz und fügen Installationen später hinzu, wenn der Workload sie benötigt.
Benötigen alle Code-Interpreter-Aufgaben Netzwerkzugriff?
Nein. Viele Analyse-Workflows arbeiten vollständig offline, sobald die Benutzerdateien hochgeladen sind, was das Ausführungsmodell einfacher hält.
Was sollte der Benutzer nach der Ausführung sehen?
Das Ergebnis, generierte Artefakte und ein präzises Protokoll oder eine Fehlerzusammenfassung, mit der Option, Code zu inspizieren oder die Aufgabe erneut auszuführen.
