Verwenden von Sprachmodellen von Drittanbietern mit ArcGIS—ArcGIS Pro

Das Toolset "Textanalyse" in der Toolbox "GeoAI" enthält Werkzeuge für Textverarbeitungs-Tasks, wie zum Beispiel Textklassifizierung, Entitätenextraktion und Textübersetzung. Die NLP-Modelle (Natural Language Processing, Verarbeitung natürlicher Sprache), die mit diesen Werkzeugen erstellt werden, basieren auf Sprachmodellen, wie zum Beispiel BERT, RoBERTa und T5, und sogenannten großen Sprachmodellen (Large Language Models, LLMs), wie zum Beispiel Mistral, und ermöglichen Hochleistungstextanalysen.

Obwohl diese vordefinierten Modelle robust sind, benötigen Sie möglicherweise einen benutzerdefinierten NLP-Workflow, zum Beispiel beim Verwenden eines LLM für das Standardisieren von Adressen, das Durchführen von Stimmungsanalysen oder das Extrahieren benutzerdefinierter Entitäten oder Beziehungen, was durch das Toolset "Textanalyse" derzeit nicht unterstützt wird. Um diesen Anforderungen gerecht zu werden, können Sie ArcGIS mit Sprachmodellen von Drittanbietern integrieren. Dazu gehören Open-Source-LLMs sowie in der Cloud gehostete kommerzielle LLMs, auf die mit einer Web-API zugegriffen wird. Bedenken Sie immer, dass bei Verwendung eines im Web gehosteten LLM die Daten, die Sie verarbeiten, zur Verarbeitung an den LLM-Anbieter gesendet werden. Python-Entwickler können eine benutzerdefinierte NLP-Funktion zum Integrieren mit externen Modellen und Packen ihres Modells als Esri Deep-Learning-Paket (.dlpk-Datei) für die Verwendung mit den folgenden Werkzeugen erstellen:

Benutzerdefinierte Python-NLP-Funktion

Sie können in Python eine NLP-Funktion zum Integrieren von Sprachmodellen von Drittanbietern in eine Textverarbeitungspipeline erstellen. NLP-Funktionen verarbeiten Textdaten und führen verschiedene Textverarbeitungs-Tasks aus.

Die Methoden der NLP-Funktion sind in der folgenden Tabelle aufgelistet und in den folgenden Unterabschnitten ausführlicher beschrieben.


Methode	Beschreibung
__init__	Initialisieren der Instanzvariablen, wie zum Beispiel name, description, und weiterer Attribute, die für die NLP-Funktion erforderlich sind.
initialize	Laden des NLP-Modells und Einrichten der Erstkonfigurationen. Verwenden Sie diese Methode am Anfang der Python-NLP-Funktion.
getParameterInfo	Definieren der Parameter, die von der NLP-Funktion akzeptiert werden. Dazu gehören die Konfigurationseinstellungen, die zum Laden des Modells oder Verbinden mit dem Modell erforderlich sind, sowie die Parameter, die für die Textverarbeitung erforderlich sind.
getConfiguration	Beschreiben der Verarbeitung der Eingaben und der Generierung der Ausgaben durch das Werkzeug. Dazu gehören Details für die Vorverarbeitungs- oder Nachbearbeitungsschritte, die für die Funktion erforderlich sind.
predict	Die Funktion, die das Konvertieren von Eingabetext in die gewünschte Ausgabe übernimmt. Sie verwendet definierte Parameter und eine Verarbeitungslogik, um das Endergebnis zu erzeugen.

Funktionsmethoden

Die Methoden der NLP-Funktion werden nachfolgend beschrieben.

init

Die Methode __init__ ist der Konstruktor der benutzerdefinierten NLP-Funktion und initialisiert Instanzvariablen, wie zum Beispiel Name, Beschreibung und weitere erforderliche Attribute. Diese Methode legt die Eigenschaften fest, mit denen das Verhalten und die Beschreibung der NLP-Funktion definiert werden.

Der Konstruktor erstellt eine Instanz einer benutzerdefinierten NLP-Klasse mit allen Attributen, die für die Verarbeitung und die Analyse erforderlich sind. Beim Erstellen einer Instanz einer NLP-Klasse stellt diese Methode sicher, dass die erforderlichen Einstellungen und Standardwerte verfügbar sind. Wenn zum Beispiel die NLP-Funktion bestimmte Einstellungen wie Pfade zu Modellen oder spezielle Token benötigt, dann können diese in dieser Methode eingerichtet werden.

class MyTextClassifier:
    def __init__(self, **kwargs):
        """
        It sets up the initial state of an object by defining its attributes,
        such as name, description, and other properties.

        """
        self.name = "Text classifier"
        self.description = '''The `MyTextClassifier` class is designed to perform text classification tasks
                            such as categorizing text data into predefined categories.'''
        # Additional initialization code here
        ...

initialize

Die Methode initialize wird am Anfang der benutzerdefinierten Python-NLP-Funktion aufgerufen. An diese Methode wird das Argument kwargs['model'] übergeben. Das Argument kwargs['model'] ist der Pfad zur Esri Modelldefinitionsdatei (.emd). Diese Methode sollte zum Laden der Modellgewichtungen beim Einrichten des NLP-Modells verwendet werden, damit eine Referenz für nachfolgende Operationen vorhanden ist.

def initialize(self, **kwargs):
    """
    Initialize model parameters, such as loading pretrained model weights.
    """
    json_file = kwargs['model']
    with open(json_file, 'r') as f:
        self.json_info = json.load(f)
    
    # access the model path in the model definition file
    model_path = json_info['ModelFile']
    # load your model and keep an instance for the model
    self.model = load_your_model(model_path)
    
    # Additional initialization code here
    ...

getParameterInfo

Die Methode getParameterInfo wird durch die Textanalysewerkzeuge nach der Methode initialize aufgerufen. In ihr werden die vom Modell benötigten Parameter definiert. Diese Methode gibt eine Liste der von der benutzerdefinierten NLP-Funktion erwarteten Eingabeparameter zurück. Jeder Parameter wird unter Verwendung eines Wörterbuchs, in dem Name, Datentyp, Anzeigename und Beschreibung des Parameters enthalten sind, und eines booleschen Parameters, der angibt, ob dieser Parameter erforderlich ist, wie nachfolgend dargestellt beschrieben.

def getParameterInfo(self):
    return [
        {
            "name": "class_names",
            "dataType": "string",
            "required": True,
            "displayName": "class_names",
            "description": "Comma-separated list of class names used for classification.",
            "value": "positive,negative"
        },
        {
            "name": "prompt",
            "dataType": "string",
            "required": False,
            "displayName": "prompt",
            "description": "The number of samples processed in one forward pass through the model.",
            "value": "Classify the following text into the defined classes."
        },
        # Additional code here
        ...
    ]

Diese Methode gibt eine Liste mehrerer Wörterbücher zurück, in denen jeweils ein Parameter beschrieben ist. Die Schlüsselattribute des Wörterbuchs sind:

name: Ein Zeichenfolgebezeichner für den Parameter
dataType: Der Datentyp, den der Parameter akzeptiert, wie zum Beispiel Zeichenfolge, boolescher Wert oder Liste
value: Der Standardwert für den Parameter
required: Ein boolescher Wert, der angibt, ob der Parameter erforderlich ist
displayName: Ein benutzerfreundlicher Name für den Parameter
domain: Die zulässigen Werte
description: Eine detaillierte Beschreibung des Parameters

Die Liste der Parameter wird dem Benutzer über die Modellargumente des benutzerdefinierten Modells in den Textanalysewerkzeugen angezeigt. Benutzer des Modells können diese Werte interaktiv in der Benutzeroberfläche eines Werkzeugs festlegen oder programmgesteuert als Schlüsselwortargumente an die Methode getConfiguration übergeben.

getConfiguration

Mit der Methode getConfiguration werden die Parameter für die NLP-Funktion eingerichtet und verwaltet. An sie werden Schlüsselwortargumente mit den Parametern, die durch Benutzer des Modells über das Werkzeug aktualisiert oder programmgesteuert bereitgestellt wurden, übergeben. Anhand der aktualisierten Parameter steuert diese Methode auch, wie die Funktion die Daten verarbeitet und ausgibt. Diese Methode wird nach der Methode getParameterInfo, aber vor der Methode predict aufgerufen. Der Rückgabewert der Funktion ist ein Wörterbuch, in dem der Wert des Parameters batch_size enthalten ist. Dieser Wert gibt an, wie viele Zeichenfolgen das Modell gleichzeitig verarbeiten kann. Der Rückgabewert der Methode teilt dem Werkzeug mit, wie die Eingabedaten geteilt werden müssen, damit das Modell die einzelnen Batches nacheinander verarbeiten kann.

def getConfiguration(self, **kwargs):
    """
    This method configures the supported NLP function parameters and
    controls further processing based on them.
    """
    # Set the class names from the provided arguments
    self.class_names = kwargs.get("class_names", "")
    self.prompt = kwargs.get("prompt", "")
    # Set the batch size, limiting it to a maximum of 4
    if kwargs.get("batch_size", 0) > 4:
        kwargs["batch_size"] = 4
       
    # Additional code here
    ...
    
    # Return the updated parameter values
    return kwargs

Im obigen Beispiel wird die benutzerdefinierte NLP-Funktion mit den folgenden Schritten konfiguriert:

Festlegen des Parameters class_names anhand der angegebenen Argumente.
Festlegen des Parameters prompt anhand der angegebenen Argumente.
Begrenzen des Parameters batch_size auf ein Maximum von 4, wenn ein größerer Wert angegeben wurde.
Zurückgeben der aktualisierten Parameterwerte.

predict

Die Methode predict führt eine Inferenz aus, das heißt, sie generiert Vorhersagen mit dem NLP-Modell. An diese Methode wird ein FeatureSet mit den Eingabe-Features (bzw. Zeilen im Fall einer Tabelle) und ein kwargs-Argument, mit dem Feldnamen, der die Eingabezeichenfolgen enthält, übergeben. Diese Methode gibt die Ergebnisse in Form eines FeatureSet-Objektes zurück. Ein typischer Workflow sieht wie folgt aus:

Extrahieren des zu verarbeitenden Eingabetextes aus dem angegebenen FeatureSet und Vorverarbeiten dieses Textes entsprechend den Anforderungen des Modells.
Anwenden des NLP-Modells auf den vorverarbeiteten Text, um Vorhersagen zu generieren.
Optimieren oder Formatieren der Vorhersagen des Modells nach Bedarf.
Packen der verarbeiteten Vorhersagen in ein FeatureSet-Objekt und Zurückgeben dieses Objektes.

def predict(self, feature_set: FeatureSet, **kwargs):
    """
    Predicts the classification of text data from the input FeatureSet and returns a new FeatureSet with the predictions.
    """
    # read the text from the input Featureset, when calling this function from ArcGIS Pro tools, be sure to use the name of the column that contains the text data instead of `input_str`.
    field = kwargs["input_field"]
    input_text = feature_set.df[field].to_list() 
    # Preprocessing input code here
    # 
    ... 
    
    # Make Predictions
    results = self.model.predict(input_text, self.class_names, self.prompt)
    
    # Additional code here
    ... 
    
    # Create featureset
    feature_dict = {
        "fields": [
            {"name": "input_str", "type": "esriFieldTypeString"},
            {"name": "class", "type": "esriFieldTypeString"}
        ],
        'geometryType': "",
        'features': [{'attributes': {'input_str': inputs, "class": result}}]
    }
    
    # Return the featureset
    return FeatureSet.from_dict(feature_dict)

Esri EMD-Datei

Fügen Sie nach dem Erstellen einer benutzerdefinierten Python-NLP-Funktion eine Referenz zu dieser Funktion in der .emd-Datei ein, indem Sie sie neben dem Parameter InferenceFunction angeben. Damit wird sichergestellt, dass die .emd-Datei ordnungsgemäß mit der Funktion verknüpft wird, damit sie in einer NLP-Verarbeitungspipeline verwendet werden kann.

{
    "InferenceFunction": "MyTextClassifier.py",
    "ModelType": "TextClassifier",
    "OutputField": "ClassLabel",
    "Labels": [
        "positive",
        "negative"
    ],


    # additional keys here
    ...
}

Hinweis:

Die .emd-Datei muss die folgenden Schlüssel enthalten:

InferenceFunction: Geben Sie den Namen der Datei an, in der die benutzerdefinierte NLP-Funktion enthalten ist.
ModelType: Geben Sie den Typ des Modells basierend auf dessen Aufgabe an. Unterstützte Werte: TextClassifier, SequenceToSequence und EntityRecognizer.
OutputField: Geben Sie den Namen des Ausgabefeldes an, in dem die Ergebnisse für TextClassifier- oder SequenceToSequence-Modelle gespeichert werden sollen.

Benutzerdefinierte DLPK-Datei

Um die Einrichtung einer benutzerdefinierten NLP-Funktion abzuschließen, erstellen Sie eine .dlpk-Modelldatei. Die .dlpk-Datei ermöglicht Ihnen die Verwendung eines Models mit den Inferenzwerkzeugen im Toolset "Textanalyse".

Organisieren Sie die Dateien wie folgt:

Erstellen Sie einen Ordner, und fügen Sie die Datei mit der benutzerdefinierten NLP-Funktion (zum Beispiel MyTextClassifier.py) und die Esri .emd-Datei (zum Beispiel TextClassifier.emd) ein. Der Name des Ordners muss mit dem Namen der .emd-Datei übereinstimmen.
```
TextClassifier/
├── MyTextClassifier.py
└── TextClassifier.emd
```
Fügen Sie alle zusätzlichen Dateien und Ordner, die für die NLP-Funktion erforderlich sind, ein.
Komprimieren Sie den Ordner in ein ZIP-Archiv. Geben Sie der .zip-Datei den Namen der .emd-Datei mit der Erweiterung .dlpk. Diese .dlpk-Datei kann jetzt mit den Inferenzwerkzeugen im Toolset "Textanalyse" verwendet werden.

Feedback zu diesem Thema?