12-Faktoren-Agenten: Entwurfsprinzipien für den Aufbau zuverlässiger LLM-Anwendungen in Produktionsqualität

Allgemeine Einführung

“12-Faktoren-Agenten" Dabei handelt es sich nicht um eine spezifische Softwarebibliothek oder ein Framework, sondern um eine Reihe von Entwurfsprinzipien für den Aufbau zuverlässiger, skalierbarer und leicht zu wartender LLM-Anwendungen (Large Language Model). Dieses Projekt wurde vom Entwickler Dex initiiert, der feststellte, dass viele Teams bei der Entwicklung von kundenorientierten Funktionen mit Hilfe bestehender AI Intelligent Body-Frameworks problemlos ein 70-80%-Qualitätsniveau erreichen konnten, dass es aber außerordentlich schwierig war, diesen Engpass in Produktionsumgebungen zu durchbrechen. Die Ursache liegt darin, dass viele fortschrittliche Frameworks zu viele der zugrundeliegenden Steuerelemente verbergen, was dazu führt, dass Entwickler ein Reverse Engineering durchführen oder ganz von vorne anfangen müssen, wenn tiefgreifende Anpassungen und Optimierungen erforderlich sind. Daher lehnt sich dieses Projekt an die Idee der klassischen Softwareentwicklungsmethodik "12-Factor App" an und schlägt 12 Kernprinzipien vor. Ziel ist es, Software-Ingenieuren einen Leitfaden an die Hand zu geben, mit dem sie modulare KI-Funktionen schrittweise und zuverlässig in bestehende Produkte integrieren können, anstatt sie von Grund auf neu zu schreiben. Der Kerngedanke ist, dass großartige KI-Anwendungen im Wesentlichen immer noch großartige Software sind, deren Hauptteil aus deterministischem Code bestehen sollte, wobei die Magie der LLM genau dort eingesetzt wird, wo sie am meisten benötigt wird.

Liste der Kurse

• Vorwort:Wie wir hierher kamen: eine kurze Geschichte der Software
• Grundsatz I:Natürliche Sprache für Tool-AufrufeStable mapping of the user's natural language input to one or more specific tool (function) calls.
• Grundsatz II:Übernehmen Sie die Kontrolle über Ihre StichwörterVersionskontrolle und Verwaltung von Prompts, als ob sie Teil des Kerncodes der Anwendung wären, anstatt dynamisch generiert zu werden.
• Grundsatz III:Übernehmen Sie die Kontrolle über Ihr KontextfensterDie genaue Kontrolle des kontextuellen Inhalts der Eingaben an das LLM ist der Schlüssel zur Erreichung von Zuverlässigkeit.
• Grundsatz IV:Tools als strukturierter OutputTools: Betrachten Sie Tools als eine Möglichkeit, den LLM dazu zu zwingen, eine strukturierte Ausgabe zu produzieren, nicht nur eine Sammlung von Funktionen.
• Grundsatz V:Harmonisierung des Umsetzungsstatus mit dem GeschäftsstatusKombination des Betriebszustands der Intelligenzen mit dem Kerngeschäftszustandsmodell der Anwendung, um Zustandskonsistenz zu erreichen.
• Grundsatz VI:Start/Pause/Fortsetzen über einfache APIsSicherstellen, dass langwierige Aufgaben von Intelligenzen über einfache Schnittstellen von externen Systemen gesteuert werden können.
• Grundsatz VII:Interaktion mit Menschen durch Tool-AufrufeWenn ein intelligentes Programm eine menschliche Eingabe oder Überprüfung erfordert, sollte es durch einen Standard-Tool-Aufruf ausgelöst werden, nicht durch eine spezielle Handhabung.
• Grundsatz VIII:Übernehmen Sie die Kontrolle über Ihren KontrollflussDie Kerngeschäftslogik und die Prozesstransformationen der Anwendung sollten von deterministischem Code geleitet werden und nicht vollständig dem Ermessen des LLM überlassen werden.
• Grundsatz IX:Komprimierung von Fehlermeldungen im KontextfensterWenn ein Werkzeug nicht ausgeführt werden kann, wird seine Fehlermeldung zusammengefasst und an den LLM zur Korrektur zurückgegeben.
• Grundsatz X:Aufbau einer kleinen, fokussierten IntelligenzDie Tendenz geht dahin, mehrere kleine, kompakte Intelligenzen zu kombinieren, anstatt eine große Intelligenz aufzubauen, die alles kann.
• Grundsatz XI:Überall auslösen, überall interagierenIntelligentsia sollte von verschiedenen Ereignisquellen ausgelöst werden können (z.B. API-Anfragen, Datenbankänderungen, zeitgesteuerte Aufgaben) und auf der Plattform interagieren können, auf der sich der Benutzer befindet (z.B. Slack, E-Mail).
• Grundsatz XII:Entwurf einer Intelligenz als zustandsloser ReduziererIn Anlehnung an Redux-Ideen ist der Smart Body als reine Funktion konzipiert, die den aktuellen Zustand und die Ereignisse empfängt und den neuen Zustand zurückgibt.

Hilfe verwenden

Die "12-Faktoren-Agenten" sind eine Reihe von Ideen und architektonischen Prinzipien, die keinen Installationsprozess haben. Es wird in dem Sinne "verwendet", dass Entwickler diese Prinzipien in ihren eigenen Projekten übernehmen und anwenden. Im Folgenden finden Sie eine detaillierte Beschreibung, wie Sie diese 12 Prinzipien in Ihrer Softwareentwicklungspraxis anwenden können.

Kernphilosophie: KI-Anwendungen sind in erster Linie Software

Bevor wir beginnen, ist es wichtig, die Kernphilosophie zu verstehen, dass der überwiegende Teil des Codes einer so genannten "KI-Anwendung" oder "KI-Intelligenz" traditioneller, deterministischer Software-Engineering-Code sein sollte, und dass LLM-Aufrufe nur ein Teil des Puzzles sind, der genau an dem Punkt verwendet wird, an dem das Verstehen natürlicher Sprache oder die Entscheidungsfindung erforderlich ist. Verstehen, Generieren oder Entscheiden natürlicher Sprache. Anstatt die Kontrolle über die gesamte Anwendung an eine "Request-Tool-Loop"-Blackbox zu übergeben, sollten Entwickler den LLM als eine Funktion betrachten, die mit speziellen Fähigkeiten aufgerufen werden kann.

Detailliertes Verfahren für die Anwendung jedes Prinzips

Grundsatz 1: Natürliche Sprache für Tool-Aufrufe
Dies ist der Einstiegspunkt für die Intelligenz zur Interaktion mit der Außenwelt. Wenn Sie eine Benutzereingabe erhalten (z. B. "Helfen Sie mir, das Wetter in Peking von gestern zu überprüfen"), brauchen Sie einen zuverlässigen Mechanismus, um sie in einen Funktionsaufruf umzuwandeln, z. B. search_weather(date="2025-07-21", city="北京").

• ArbeitsweiseVerwenden Sie die LLM-Funktion "Funktionsaufruf" oder "Werkzeugverwendung". In der an das Modell gesendeten Anfrage geben Sie nicht nur Benutzereingaben an, sondern auch eine detaillierte JSON-Schema-Definition der Liste der Werkzeuge (Funktionen), die aufgerufen werden können, und ihrer Parameter. Das Modell gibt ein JSON-Objekt zurück, das angibt, welche Funktion aufgerufen werden soll und welche Parameter übergeben werden sollen. Ihr Code ist für das Parsen dieses JSON und die Ausführung der entsprechenden Funktion verantwortlich.

Grundsatz 2: Machen Sie sich Ihre Aufforderungen zu eigen.
Erzeugen Sie in Ihrem Code nicht dynamisch komplexe Hinweiswörter. Das macht die Fehlersuche und Iteration sehr schwierig.

• ArbeitsweisePrompts: Behandeln Sie Ihre Prompts als statische Konfigurationsdateien (z.B. .txt vielleicht .md Datei) zu verwalten. Laden Sie diese Cue-Word-Vorlagen in Ihren Code und füllen Sie sie mit Variablen. Das Einbinden dieser Cue-Word-Dateien in ein Versionskontrollsystem wie Git ist wie die Verwaltung der main.py vielleicht index.js Dasselbe. Auf diese Weise können Sie jede Änderung des Stichworts verfolgen und leicht testen und zurücksetzen.

Grundsatz 3: Eigenes Kontextfenster
Das Kontextfenster ist das einzige "Gedächtnis" des LLM. Die Qualität der Eingabe bestimmt direkt die Qualität der Ausgabe. Stopfen Sie nicht wahllos alle historischen Nachrichten hinein.

• ArbeitsweiseImplementierung einer präzisen Strategie zur Kontextbildung. Vor jedem Aufruf des LLM sollte Ihr Code sorgfältig Nachrichten auswählen und kombinieren, die auf den Anforderungen der jeweiligen Aufgabe basieren. Dazu können gehören: eine Systemaufforderung, die wichtigsten historischen Meldungen, relevante Dokumentationsausschnitte (RAG-Ergebnisse) und das letzte Problem des Benutzers. Ziel ist es, dem LLM die wichtigsten Informationen zur Verfügung zu stellen, die zur Lösung des jeweiligen Problems erforderlich sind.

Grundsatz 4: Werkzeuge sind nur strukturierte Ergebnisse
Obwohl diese Funktionen als "Werkzeuge" bezeichnet werden, sind sie aus einer anderen Perspektive die einzige zuverlässige Möglichkeit für Sie, den LLM zu zwingen, das von Ihnen gewünschte wohlgeformte JSON auszugeben.

• ArbeitsweiseDefinieren Sie den LLM als "Werkzeug", wenn Sie ihn benötigen, um Informationen für Sie zu extrahieren, zu kategorisieren oder um eine Aufgabe zu erledigen, die ein deterministisches Ausgabeformat erfordert. Wenn Sie zum Beispiel Namen und Firmen aus einem Text extrahieren müssen, können Sie eine extract_entities(person: str, company: str) Um dieses Tool "aufrufen" zu können, muss LLM Ausgaben in diesem Format erzeugen.

Grundsatz 8: Eigener Kontrollfluss
Dies steht im Gegensatz zu vielen automatisierten Intelligenz-Frameworks, ist aber entscheidend. Was die Anwendung als Nächstes tun soll, sollte nicht ausschließlich durch LLM in einer Schleife bestimmt werden.

• ArbeitsweiseDeterministischer Code (z. B. if/else, switch-Anweisungen oder Zustandsautomaten) zum Schreiben von Kerngeschäftsprozessen. Zum Beispiel könnte ein Auftragsabwicklungsprozess so aussehen:接收订单 -> [LLM分类意图] -> if (查询) then call_query_api() else if (退货) then call_refund_api()Hier ist der LLM nur für den Schritt "tu klassifizieren" verantwortlich. Hier ist der LLM nur für den Schritt "tu klassifizieren" verantwortlich, und der gesamte Prozess wird von Ihrem Code gesteuert. Dies macht das Systemverhalten vorhersehbar und debuggbar.

Prinzip 10: Kleine, gezielte Agenten
Versuchen Sie nicht, eine "Superintelligenz" zu schaffen, die alles kann.

• ArbeitsweiseZerlegung komplexer Aufgaben. Ein Kundenbetreuungssystem kann beispielsweise in eine Intelligenz für die Absichtserkennung, eine Intelligenz für die Abfrage der Wissensbasis und eine Intelligenz für die Bearbeitung von Aufträgen unterteilt werden. Ihr Hauptkontrollflusscode (Prinzip acht) ist für das Routing und die Planung zwischen diesen Intelligenzen verantwortlich. Jede der kleineren Intelligenzen hat ihr eigenes gezieltes Stichwort (Grundsatz zwei) und ihren eigenen Werkzeugsatz (Grundsatz vier).

Grundsatz XII: Machen Sie Ihren Agenten zu einem zustandslosen Reduktionsmittel
Dies basiert auf den Ideen der Zustandsverwaltung von Front-End-Frameworks wie Redux und kann die Testbarkeit und Vorhersagbarkeit eines Systems erheblich verbessern.

• ArbeitsweiseImplementieren Sie Ihre Intelligenz, oder einen ihrer Schritte, als reine Funktion mit einer Signatur wie (currentState, event) => newState.
  • currentState sind alle Zustände der aktuellen Anwendung.
  • event ist ein Ereignis, das gerade eingetreten ist (z. B. eine neue Nachricht vom Benutzer oder ein von der API zurückgegebenes Ergebnis).
  • Der Rückgabewert einer Funktion newState ist der aktualisierte Zustand.
    Die Funktion selbst ist zustandslos (sie hängt nicht von externen Variablen ab), und alles, was sie tut, ist, die Ausgabe auf der Grundlage der Eingabe zu berechnen. Das macht es sehr einfach, Unit-Tests zu schreiben: Sie müssen nur verschiedene currentState im Gesang antworten event Kombination, und behauptet dann newState Ob sie den Erwartungen entspricht.

Wenn Sie diese Grundsätze befolgen, können Sie LLM-Anwendungen erstellen, die in ihrem Verhalten stabiler sind, leichter zu debuggen sind und mit bestehenden Softwaresystemen harmonieren.

Anwendungsszenario

1. Hinzufügen von KI-Funktionen zu bestehenden SaaS-Produkten
   Bei einem ausgereiften SaaS-Produkt, das bereits über eine stabile Geschäftslogik verfügt (z. B. CRM, Projektmanagement-Tools), möchten die Entwickler schrittweise KI-Funktionen einführen, ohne den Kerncode neu zu schreiben. Übersetzen Sie beispielsweise die natürlichsprachlichen Anweisungen eines Benutzers ("Erstellen Sie eine Aufgabe, die nächste Woche fällig ist, und weisen Sie sie Zhang San zu") in einen Aufruf einer bestehenden API, wobei die Stabilität der Kernlogik für die Aufgabenerstellung gewahrt bleibt, indem Sie die Prinzipien eins und acht anwenden.
2. Entwicklung hochwertiger KI-Assistenten für Endnutzer
   Bei der Entwicklung eines KI-Assistenten, der direkt mit zahlenden Kunden interagiert, sind Zuverlässigkeit und Benutzerfreundlichkeit entscheidend. Die direkte Verwendung von generischen Frameworks kann bei komplexen Fällen oder Grenzfällen zu unvorhersehbarem Verhalten führen. Durch die Anwendung dieser Grundsätze, insbesondere Grundsatz III (Beherrschung des Kontexts), Grundsatz VIII (Beherrschung des Kontrollflusses) und Grundsatz IX (Komprimierung von Fehlermeldungen), kann sichergestellt werden, dass der Assistent Probleme elegant bewältigt oder bei Bedarf gemäß Grundsatz VII (Interaktion mit Menschen) Hilfe holt, anstatt falsche Antworten zu geben oder abzustürzen.
3. Vermarktung von AI-Prototypen
   Viele Teams verwenden fortschrittliche Frameworks, um schnell einen beeindruckenden Prototyp (Demo) zu erstellen, aber wenn sie bereit sind, ihn als vollwertiges Produkt zu veröffentlichen, stellen sie fest, dass der Prototyp in realen, komplexen Szenarien instabil ist (die Qualität bricht nicht 80%). An diesem Punkt bietet 12-Factor Agents eine Reihe von "Refactoring"-Richtlinien. Teams können ihren Prototypencode mit robusteren Softwareentwicklungspraktiken, die diesen Prinzipien folgen, überarbeiten, wie z. B. das Refactoring mehrdeutiger Kontrollflüsse (loop-until-done) in explizite Zustandsautomaten (Prinzip Acht) und die Vereinheitlichung fragmentierter Eingabeaufforderungen und Zustandsverwaltung (Prinzipien Zwei und Fünf).

QA

1. Ist "12-Faktoren-Agenten" ein installierbares Software-Framework?
   Das ist es nicht. Es ist kein Ort wie LangChain oder Griptape, wo man direktpip installDas Softwarepaket. Es handelt sich um eine Reihe von Entwurfsphilosophien und architektonischen Prinzipien, die Entwicklern als Anleitung dienen sollen, wie sie ihren Code und ihre Denkweise besser organisieren können, um zuverlässige LLM-Anwendungen zu erstellen. Es ist ein Dokument, eine Methodik.
2. Warum den Kontrollfluss selbst in die Hand nehmen und nicht LLM entscheiden lassen? Ist das nicht die Schönheit der Intelligenzen?
   Dies ist einer der Kerngedanken der Methodik. Der Reiz, den Kontrollfluss (d. h. "was als Nächstes zu tun ist") vollständig vom LLM bestimmen zu lassen, liegt in seiner Flexibilität und seinem Potenzial zur Entdeckung neuer Pfade. In einer Produktionsumgebung ist diese Ungewissheit jedoch mit erheblichen Risiken und Schwierigkeiten bei der Fehlerbehebung verbunden. Wenn bei einer Anwendung etwas schief läuft, ist es schwierig festzustellen, ob das Problem in der Entscheidungsfindung des LLM oder in der Ausführung des Tools liegt." 12-Factor Agents" befürwortet, dass zentrale, risikoreiche Geschäftsprozesse in deterministischem Code (z. B. Zustandsautomaten) definiert werden und dass an bestimmten Punkten des Prozesses LLMs aufgerufen werden können, um lokale Entscheidungen zu treffen (z. B. Klassifizierung, Extraktion von Informationen usw.). Auf diese Weise werden die Fähigkeiten der LLMs genutzt und gleichzeitig die allgemeine Vorhersagbarkeit und Stabilität des Systems gewährleistet.
3. Bedeutet diese Reihe von Prinzipien, dass ich bestehende KI-Frameworks überhaupt nicht verwenden kann?
   Nicht wirklich. Sie können durchaus bestehende Rahmenwerke verwenden und dabei diese Grundsätze befolgen. Der Schlüssel liegt darin, wie Sie sie verwenden. Betrachten Sie ein Framework als eine "Bibliothek", die praktische Werkzeuge bereitstellt, und nicht als ein "Framework", das den Ablauf Ihrer gesamten Anwendung steuert. Sie können z. B. die von einem Framework bereitgestellten Funktionen zum Parsen von Toolcalls nutzen, den Hauptkontrollfluss jedoch selbst schreiben, oder das von ihm bereitgestellte RAG-Modul (Retrieval Augmentation Generation) zum Auffüllen des Kontexts verwenden, die Einzelheiten dieses Kontexts unterliegen jedoch gemäß Grundsatz 3 Ihrer genauen Kontrolle. Es geht darum, die Kontrolle über wichtige Teile der Anwendung zu behalten, anstatt alles an das Framework auszulagern.
4. Ist diese Reihe von Grundsätzen für traditionelle Software-Ingenieure ohne KI-Hintergrund leicht zu befolgen?
   Es ist so einfach, dass man sogar sagen könnte, dass diese Grundsätze für gute Software-Ingenieure wie geschaffen sind. Vieles davon (z. B. Versionskontrolle, Zustandsmanagement, Modularität, deterministischer Kontrollfluss) ist bewährte Praxis der Softwaretechnik. Es ermutigt Ingenieure, das LLM mit ihrer bereits vertrauten und zuverlässigen technischen Denkweise zu navigieren, anstatt von ihnen zu verlangen, ein völlig neues probabilistisches Programmierparadigma zu lernen. Es "degradiert" LLM zu einer leistungsstarken, aber sorgfältig verwalteten "Komponente", die es Ingenieuren ermöglicht, in ihren eigenen vertrauten Bereichen zu arbeiten.