在 ArcGIS 中使用第三方语言模型—ArcGIS Pro

GeoAI 工具箱中的文本分析工具集提供了一组用于文本处理任务的工具，例如文本分类、实体提取和文本翻译。使用这些工具创建的自然语言处理 (NLP) 模型构建在诸如 BERT、RoBERTa 和 T5 等语言模型以及诸如 Mistral 等大型语言模型 (LLM) 之上，以确保高性能的文本分析。

虽然这些预构建的模型非常强大，但您可能需要自定义 NLP 工作流，例如在使用 LLM 标准化地址、执行情感分析或提取文本分析工具集当前不支持的自定义实体或关系时。为了满足这些需求，您可以将 ArcGIS 与外部第三方语言模型进行集成。其中包括开源 LLM 以及使用 web API 访问的云托管商业 LLM。请记住，如果您使用的是 web 托管 LLM，则会将您正在处理的数据发送给 LLM 提供商进行处理。 Python 开发人员可以编写自定义 NLP 函数以与外部模型进行集成，并将其模型打包为 Esri 深度学习包（.dlpk 文件），以供以下工具使用：

自定义 Python NLP 函数

可以在 Python 中创建 NLP 函数，以将第三方语言模型集成到文本处理管道中。 NLP 函数用于处理文本数据并执行各种文本处理任务。

下表中列出了 NLP 函数方法，并将在后续部分中对其进行更详尽的阐述。


方法	描述
__init__	初始化实例变量，例如 name、description，以及其他对 NLP 函数至关重要的属性。
initialize	加载 NLP 模型并设置任何初始配置。在 Python NLP 函数的开头使用此方法。
getParameterInfo	定义 NLP 函数接受的参数。包括加载或连接模型所需的任何配置设置以及文本处理所需的参数。
getConfiguration	介绍该工具如何执行输入处理并生成输出。包括该函数所需的任何预处理或后处理步骤的详细信息。
predict	负责将输入文本转换为所需输出的函数。它使用已定义的参数和处理逻辑以生成最终结果。

函数方法

以下介绍了 NLP 函数方法。

init

__init__ 方法是自定义 NLP 函数的构造函数，用于初始化实例变量，例如名称、描述和其他必要属性。此方法用于设置相应属性，这些属性将定义 NLP 函数的行为和特征。

构造函数将创建自定义 NLP 类的实例，该实例具有处理和分析所需的所有属性。当创建 NLP 类的实例时，此方法可确保其具有所需的设置和默认值。例如，如果 NLP 函数需要特定设置（例如模型路径或特殊令牌），则可以在此方法中进行设置。

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

将在自定义 Python NLP 函数启动时调用 initialize 方法，并将 kwargs['model'] 传递给此方法。 kwargs['model'] 参数是 Esri 模型定义文件 (.emd) 的路径。该方法用于加载模型权重以设置 NLP 模型，由此确保后续操作对其进行引用。

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

“文本分析”工具将在 initialize 方法之后调用 getParameterInfo 方法，该方法用于定义模型所需的参数。此方法将返回自定义 NLP 函数所需的输入参数列表。将使用字典来描述每个参数，其中包含参数的名称、数据类型、显示名称和描述，以及指示该参数是否为必填项的布尔参数，如下所示。

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
        ...
    ]

该方法将返回一个字典列表，每个字典描述一个参数。该字典的主要属性如下：

name - 参数的字符串标识符
dataType - 参数所接受的数据类型，例如字符串、布尔值或列表
value - 参数的默认值
required - 指示参数是否为必填项的布尔值
displayName - 参数的用户友好名称
domain - 一组允许的值（如果适用）
description - 参数的详细描述

参数列表通过“文本分析”工具中的自定义模型的模型参数显示给用户。模型的用户可以使用工具用户界面以交互方式设置这些值，或者以编程方式将其作为关键字参数传递到 getConfiguration 方法。

getConfiguration

getConfiguration 方法用于设置并管理 NLP 函数的参数。它传递的关键字参数包含模型用户通过工具更新的参数或者以编程方式提供的参数。该方法还将根据已更新参数来控制函数处理和输出数据的方式。将在 getParameterInfo 方法之后，但在 predict 方法之前调用此方法。该函数的返回值是一个字典，其中包含 batch_size 的值，用于指示模型一次可以处理的字符串数量。该方法的返回值将告知工具如何分割输入数据，以便模型一次处理一批。

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

在以上示例中，通过执行以下操作来配置自定义 NLP 函数：

根据提供的参数设置 class_names 参数。
根据提供的参数设置 prompt 参数。
如果提供较大的值，则将 batch_size 参数限制为最大值 4。
返回已更新参数值。

predict

predict 方法将执行推断，即使用 NLP 模型生成预测。此方法将传递包含输入要素（或者表的行）的 FeatureSet 以及包含字段名称的 kwargs，该字段名称包含输入字符串。此方法将以 FeatureSet 对象的形式返回结果。以下为典型工作流：

从提供的 FeatureSet 中提取要处理的输入文本并对其进行预处理以满足模型的要求。
将 NLP 模型应用于经过预处理的文本以生成预测。
根据需要优化或格式化模型的预测。
将处理后的预测打包到 FeatureSet 对象中并将其返回。

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 文件

创建自定义 Python NLP 函数后，通过在 InferenceFunction 参数旁指定该函数以在 .emd 文件中包含对该函数的引用。由此可确保 .emd 文件正确链接到该函数，从而能够在 NLP 处理管道中使用该函数。

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


    # additional keys here
    ...
}

注：

.emd 文件必须包含以下关键字：

InferenceFunction - 指定包含自定义 NLP 函数的文件的名称。
ModelType - 根据模型的任务指示模型的类型。受支持的值为 TextClassifier、SequenceToSequence 和 EntityRecognizer。
OutputField - 提供将存储 TextClassifier 或 SequenceToSequence 模型结果的输出字段的名称。

自定义 .dlpk 文件

要完成自定义 NLP 设置，请创建 .dlpk 模型文件。借助 .dlpk 文件，您可以将模型与“文本分析”工具集中的推断工具配合使用。

按如下方式组织文件：

创建文件夹并包含自定义 NLP 函数文件（例如 MyTextClassifier.py）和 Esri .emd 文件（例如 TextClassifier.emd）。文件夹的名称必须与 .emd 文件的名称相匹配。
```
TextClassifier/
├── MyTextClassifier.py
└── TextClassifier.emd
```
包含 NLP 函数所需的任何其他文件或文件夹。
将该文件夹压缩为 ZIP 归档。重命名 .zip 文件以与 .emd 文件的名称相匹配，但扩展名为 .dlpk。此 .dlpk 文件现在已准备好与“文本分析”工具集中的推断工具配合使用

有关此主题的反馈?