Ein KI-SDK aktualisieren, ohne die Integration zu beschädigen: Vertragstests

Kompatibilität umfasst mehrere Ebenen und Fragen

Eine Aktualisierung einer KI-Integration kann unterschiedliche Änderungen mit sich bringen, die getrennt betrachtet werden sollten. Das SDK ist die Bibliothek, über die der Client mit einem Dienst kommuniziert. Die API definiert die Schnittstelle, die Anfragen entgegennimmt und Antworten zurückgibt. Die Konfiguration kann eine API-Version festlegen, und die Modell-ID gibt an, welches Modell angefordert wird. Diese Elemente hängen zusammen, sind aber nicht austauschbar. Eine Anwendung kann beispielsweise das SDK wechseln und dabei dieselbe API-Version beibehalten oder die Modell-ID ändern, ohne die Bibliothek zu aktualisieren. Welche Kombination konkret gilt, hängt vom Anbieter und vom Aufbau der Integration ab.

Deshalb ist „das Update funktioniert“ keine ausreichend präzise Prüfung. Mindestens zwei unterschiedliche Fragen sind zu beantworten. Erstens die technische: Sendet der Client weiterhin eine akzeptierte Anfrage, und kann er die empfangene Antwort sowie Fehler interpretieren? Zweitens die funktionale: Ist das Ergebnis für die Aufgabe der Anwendung weiterhin nützlich? Vertragstests befassen sich vor allem mit der ersten Frage. Für die zweite sind Bewertungen des Anwendungsverhaltens und gegebenenfalls der Modellqualität erforderlich.

Eine Änderung kann technische Prüfungen bestehen und trotzdem zu einer funktionalen Abweichung führen. Umgekehrt kann ein generierter Text bei einem manuellen Test korrekt wirken, obwohl eine Protokolleigenschaft nicht mehr angemessen interpretiert wird. Verwende daher nicht das eine Signal als Ersatz für das andere. Halte getrennt fest, was mit welchen Belegen geprüft wurde und was noch offen ist.

Die bereitgestellte Dokumentation enthält Materialien von Anbietern zu Integration, Migration und Neuerungen. Sie sind ein Ausgangspunkt, um spezifische Informationen zu finden. Die verfügbaren Auszüge belegen jedoch keinen detaillierten Vertrag, der für alle Anbieter gilt. Daher schreibt dieser Leitfaden keiner bestimmten API Felder, Typen, Fehler oder konkrete Schritte zu. Ergänze vor der Anwendung des Verfahrens das Verzeichnis anhand der aktuellen Dokumentation des Dienstes, den dein Team tatsächlich verwendet.

Den Vertrag vor Änderungen erfassen

Erfasse vor der Aktualisierung den aktuellen Zustand der Integration. Notiere Name und installierte Version des SDK, gegebenenfalls die vom Client verwendete API-Konfiguration, die konfigurierte Modell-ID sowie die Anwendungskomponente, die den Aufruf ausführt. Halte außerdem die Umgebung fest, in der der Test läuft, zum Beispiel eine Entwicklungs- oder Testkonfiguration. Speichere keine Schlüssel oder andere Geheimnisse im Verzeichnis; notiere lediglich sichere Verweise auf die Konfiguration.

Beschreibe anschließend die Schnittstelle zwischen deiner Anwendung und dem Dienst. Liste die Felder auf, die deine Anwendung sendet, die jeweils erwarteten Typen und die Felder, die laut der herangezogenen Dokumentation verpflichtend sind. Dokumentiere für die Antwort die Eigenschaften, die der Client tatsächlich ausliest, ihre erwarteten Typen und den Umgang mit vorhandenen oder fehlenden Feldern. Verwechsle nicht die Gesamtheit möglicher Daten, die ein Anbieter zurückgeben könnte, mit der Teilmenge, die deine Anwendung verarbeiten muss.

Führe dieselbe Prüfung für dokumentierte Fehler und nicht erfolgreiche Antworten durch, die der Client behandeln muss. Mache aus einer einzelnen Beobachtung keine allgemeingültige Regel. Wenn die Dokumentation eine Form, einen Status oder eine Bedingung nicht festlegt, kennzeichne sie als unbekannt oder nicht abgedeckt, statt ihr eine Bedeutung zuzuschreiben. So wird vermieden, dass ein lokaler Test als Garantie des Anbieters dargestellt wird.

Bewahre das Verzeichnis zusammen mit der Änderung oder an einem für das Team zugänglichen Ort auf. Ergänze ein Prüfdatum und den verwendeten internen Verweis auf die Dokumentation, aber keine Zugangsdaten oder Nutzerdaten. Ziel ist keine vollständige Beschreibung der gesamten API. Vielmehr sollen die tatsächlichen Abhängigkeiten der Anwendung sichtbar werden, damit Versionen anhand stabiler Kriterien verglichen werden können.

Vertragstests, ohne identische Texte zu verlangen

Ein Vertragstest sollte beobachtbare Eigenschaften der Integration prüfen und nicht allgemein einen exakt festgelegten Satz als Voraussetzung für eine generierte Antwort erzwingen. Zu den Eigenschaften, die geprüft werden können, sofern sie zum dokumentierten Vertrag und zur Verwendung in der Anwendung gehören, zählen das Vorhandensein eines erforderlichen Feldes, sein Typ, die Interpretierbarkeit der Antwort und der vorgesehene Umgang mit einem bekannten Fehlerstatus. Ob diese Prüfungen im konkreten Fall sinnvoll sind, hängt vom tatsächlichen Vertrag ab. Unterstelle keine Feldnamen oder Bedeutungen, die du nicht überprüft hast.

Ein wörtlicher Textvergleich ist besonders fragil, wenn der Dienst Inhalte generiert. Eine andere Formulierung belegt für sich genommen weder eine Protokolländerung noch, dass die Anwendung ihre Funktion nicht mehr erfüllt. Eine Antwort, die sich nicht mehr anhand der vom Client benötigten Eigenschaften interpretieren lässt, kann dagegen auf eine technische Inkompatibilität hinweisen. Ordne beide Beobachtungen getrennt ein und verwende jeweils passende Kriterien.

Nutze kontrollierte Antworten, um den Code zu testen, der Daten umwandelt. Ein Testdouble oder eine synthetische Antwort ermöglicht es, wiederholbar zu prüfen, wie sich dein Client bei vom Team festgelegten Strukturen verhält. Ein Test mit einem Double belegt jedoch nicht, dass der reale Dienst diese Struktur zurückgibt. Verringere diese Unsicherheit durch lokale Tests und begrenzte Prüfungen gegen den Dienst in einer Testumgebung, sofern Zugriff und Dokumentation dies ermöglichen.

Der folgende Code ist ein ausführbares Beispiel für die Validierung einer fiktiven internen Schnittstelle. Die Namen und Typen sind bewusst nur zur Veranschaulichung gewählt und beschreiben nicht die Antwort eines Anbieters. Der Test prüft anhand einer kontrollierten Antwort, ob Eigenschaften vorhanden sind und die erwarteten Typen haben. Er führt keine Netzwerkaufrufe aus und soll nicht die Qualität eines Modells beurteilen. Ersetze die Beispieloberfläche durch die tatsächliche Schnittstelle deines Adapters und gleiche sie mit der zugehörigen Dokumentation ab.

import unittest


def validate_response(response):
    required = {"request_id": str, "model_ref": str, "content": str}
    if not isinstance(response, dict):
        raise TypeError("Die Antwort muss ein Dictionary sein")
    for field, expected_type in required.items():
        if field not in response or not isinstance(response[field], expected_type):
            raise ValueError(f"Feld fehlt oder ist ungültig: {field}")


class ContractTest(unittest.TestCase):
    def test_accepts_controlled_response(self):
        fixture = {
            "request_id": "test-001",
            "model_ref": "demo-model",
            "content": "synthetische Antwort",
        }
        validate_response(fixture)


if __name__ == "__main__":
    unittest.main()

Lokale Tests und Prüfungen des Dienstes trennen

Teile die Teststrategie nach den Grenzen auf, die die jeweiligen Tests beobachten können. Unit-Tests können den Aufbau einer Anfrage und die Interpretation synthetischer Antworten prüfen. Adaptertests können mithilfe von Doubles kontrollieren, wie die Anwendung auf festgelegte Antworten reagiert. Prüfungen gegen einen realen Dienst ermöglichen es, die tatsächliche Integration unter den Bedingungen der Testumgebung zu untersuchen. Keine dieser Kategorien sollte so dargestellt werden, als decke sie automatisch auch die anderen ab.

Halte synthetische Daten frei von sensiblen Informationen. Verwende für Tests, die den Dienst aufrufen, eine autorisierte Testkonfiguration und für diese Umgebung geeignete Daten. Dokumentiere, ob das Ergebnis von externer Verfügbarkeit, Konfiguration oder Grenzen abhängt, die das Team nicht kontrolliert. Mache den Erfolg eines Strukturtests nicht davon abhängig, immer denselben Satz zu erhalten: Prüfe Protokolleigenschaften und behandle die Bewertung von Inhalten in einem getrennten Kriterienkatalog.

Eine nützliche Praxis ist es, kontrollierte Beispiele aufzubewahren, die für den Client relevante dokumentierte Fälle abbilden. Erläutere zu jedem Beispiel, welches Verhalten deines Codes damit geprüft wird und woher es stammt: aus einer vom Team entworfenen Fixture, einer mit Genehmigung gespeicherten Antwort oder einem aus der Dokumentation abgeleiteten Fall. Vermische diese Kategorien nicht. Eine Fixture ist eine Testeingabe und keine Bestätigung dafür, dass der Anbieter immer dieselbe Antwort zurückgibt.

Führe beim Vergleich der alten mit der neuen Version nach Möglichkeit dieselbe lokale Testsuite gegen beide Versionen deines Adapters aus. Wenn ein Test fehlschlägt, ermittle zunächst die betroffene Grenze: Anfrageerstellung, Antwortinterpretation, Konfiguration oder realer Aufruf. Entscheide anschließend, ob der Fehler auf eine dokumentierte Inkompatibilität, eine zu aktualisierende interne Annahme, eine Einschränkung des Doubles oder ein funktionales Problem hinweist, das separat bewertet werden sollte.

Migration prüfen und Unterschiede einordnen

Bevor du Abhängigkeiten änderst, lies die für den verwendeten Anbieter, das SDK und die API relevanten Migrationsanleitungen und Versionshinweise. Vergewissere dich, dass die Dokumentation zum untersuchten Produkt und zur betreffenden Version gehört. Achte auf inkompatible Änderungen, entfernte Elemente, geänderte Namen oder Typen, Anpassungen der Konfiguration und Migrationsschritte. Klärt die verfügbare Dokumentation einen Punkt nicht, fülle die Lücke nicht mit einer Vermutung. Halte die Frage fest und bitte um Bestätigung oder entwickle einen Test, mit dem sie sicher untersucht werden kann.

Ordne jeden beobachteten Unterschied nach seinen Auswirkungen ein. Eine Änderung kann inkompatibel sein, wenn der Client eine Anfrage nicht mehr erstellen oder eine benötigte Antwort nicht mehr interpretieren kann. Eine Anpassung kann erforderlich sein, wenn sich eine Erwartung des Clients ändert, auch wenn ein dokumentierter Migrationsweg existiert. Eine Änderung kann technisch mit der Integration vereinbar sein und dennoch eine gesonderte funktionale Bewertung rechtfertigen. Sie kann außerdem den von der Anwendung verwendeten Code überhaupt nicht betreffen. Die Einordnung beschreibt die nachgewiesenen Auswirkungen und keine allgemeingültige Eigenschaft des Updates.

Bewahre einen nachvollziehbaren Vergleich zwischen der alten und der neuen Version auf: Konfiguration, Abhängigkeiten, Testergebnisse und Änderungen am Adapter. Wenn ein Test fehlschlägt, entferne ihn nicht einfach, um einen erfolgreichen Durchlauf zu erzielen. Ermittle zuerst, ob die Anforderung nicht mehr gilt, der Test den Vertrag falsch abgebildet hat oder die Integration tatsächlich beschädigt wurde. Halte die Belege und die Entscheidung fest.

Zu den bereitgestellten Quellen gehören eine Migrationsanleitung für das Python-SDK der Agent Platform von Google Cloud, Materialien von Microsoft Learn zu SDK und REST-API für Azure Language sowie zu Neuerungen bei Content Understanding und ein Beitrag von OpenAI zur Weiterentwicklung seines Agents SDK. Diese Titel weisen auf relevante Dokumentation zu den jeweiligen Produkten hin. Sie reichen nicht aus, um gleichartige Felder, Versionen oder Abläufe anzunehmen oder hier nicht belegte technische Einzelheiten zuzuschreiben.

In der Testumgebung validieren und schrittweise ausrollen

Führe die erste Validierung in einer Testumgebung durch, deren Konfiguration repräsentativ ist, die aber keine unnötigen Daten oder Zugangsdaten offenlegt. Prüfe, ob die installierte Abhängigkeit der vorgesehenen Version entspricht und ob API-Konfiguration sowie Modell-ID mit dem Ziel der Aktualisierung übereinstimmen. Diese Konfigurationsprüfung verhindert, dass eine Abweichung, die möglicherweise auf eine andere Ebene zurückgeht, fälschlich einer SDK-Änderung zugeschrieben wird.

Lege die Abnahmekriterien vor der Durchführung fest. Dazu kann beispielsweise gehören, dass die vereinbarten Strukturprüfungen bestehen, der Client die von der Testsuite abgedeckten dokumentierten Fälle behandelt, die getrennten Funktionstests keine bekannte Anforderung verfehlen und für kritische Unsicherheiten eine ausdrückliche Entscheidung vorliegt. Mache solche Beispielkriterien nicht zu allgemeinen Anforderungen. Wähle die Kriterien passend zu Risiko und Einsatz deiner Anwendung.

Wenn das Ergebnis zufriedenstellend ist, plane einen schrittweisen Rollout, der zur Architektur und zu den Kontrollen deines Teams passt. Beobachte relevante technische Signale und bewahre die Möglichkeit, zur vorherigen Konfiguration zurückzukehren. Die konkrete Strategie hängt davon ab, wie das Produkt ausgerollt wird; dieser Leitfaden kann daher keinen Mechanismus vorgeben, der für alle Systeme geeignet ist. Stelle sicher, dass das Team weiß, welche Änderung ausgerollt wurde, welche Belege dafür vorliegen und unter welcher Bedingung der Rollout gestoppt oder zurückgesetzt werden soll.

Kann ein wichtiger Punkt nicht geprüft werden, etwa weil Dokumentation oder Zugriff auf eine Testumgebung fehlt oder keine überprüfbare Antwort vorliegt, verschiebe die Freigabe oder halte die Einschränkung ausdrücklich fest und benenne, wer sie akzeptiert. Dass kein Fehler beobachtet wurde, bedeutet nicht, dass der Test vollständig ist. Ebenso belegt ein erfolgreicher realer Aufruf nicht, dass alle Felder, Fehlerfälle und Anwendungsfälle kompatibel sind.

Abnahmeliste und Entscheidungsprotokoll

Prüfe vor der Freigabe, ob die Änderung klar abgegrenzt ist: vorgesehene SDK-Version, API-Konfiguration und Modell-ID, sofern relevant, sowie betroffene Anwendungskomponenten. Bestätige, dass die herangezogene Migrationsdokumentation zum richtigen Produkt gehört und die relevanten Anweisungen geprüft wurden. Beantwortet die Dokumentation eine Vertragsfrage nicht, halte sie sichtbar als Unsicherheit fest. Verwandle sie nicht ohne Beleg in eine Testerwartung.

Vergewissere dich, dass die technischen Tests Eigenschaften prüfen, die die Anwendung tatsächlich benötigt, und dass die Ergebnisse funktionaler Tests getrennt aufgeführt sind. Kennzeichne Doubles und Fixtures als kontrollierte Testdaten und nicht als garantierte Antworten des Dienstes. Halte fest, welche Tests den realen Dienst aufgerufen haben, mit welcher Konfiguration und welchen Einschränkungen. Wird eine Textänderung für das Produkt als wichtig erachtet, beschreibe das relevante funktionale Kriterium, statt sie automatisch als Vertragsbruch zu bezeichnen.

Die Entscheidung kann lauten: freigeben, aufschieben oder zurücksetzen. Eine Freigabe bedeutet, dass die festgelegten Kriterien erfüllt wurden und verbleibende Einschränkungen ausdrücklich akzeptiert sind. Aufschieben bedeutet, dass benötigte Belege fehlen oder ein Risiko noch geklärt werden muss. Zurücksetzen bedeutet, zur vorherigen Konfiguration zurückzukehren, wenn die Änderung ein vom Team als nicht akzeptabel eingestuftes Problem verursacht. Halte in allen drei Fällen fest, wer entscheidet, was beobachtet wurde und welcher Schritt als Nächstes folgt.

Ein solches Protokoll macht die Aktualisierung zu einer überprüfbaren Entscheidung und erleichtert spätere Vergleiche. Es hilft außerdem anderen Teams, eine tatsächliche Inkompatibilität von einer Verhaltensabweichung oder einer Abdeckungslücke zu unterscheiden. Für weiterführende Informationen lässt sich das Thema mit Einführungen in die Entwicklung, Vergleichen von Tools und Übersichten zu verfügbaren Optionen verknüpfen. Diese kontextuelle Navigation ersetzt jedoch keine technische Prüfung des konkreten Falls.

Weiter entdecken

Korrekturen und Transparenz

Wenn du falsche oder veraltete Angaben findest, sende uns die Seite und die zu prüfende Quelle.