Beckhoff ML XML

Einführung zur Beckhoff ML XML

Das Beckhoff-spezifische XML-Format zur Repräsentation von trainierten Machine Learning Modellen bildet eine Kernkomponente der TwinCAT Machine Learning Inference Engine und TwinCAT Neural Network Inference Engine. Die Datei wird aus einer ONNX-Datei über den TC3 Machine Learning Model Manager oder die Machine Learning Toolbox oder das bereitgestellte Python Package erstellt.

Im Gegensatz zum ONNX, kann die XML-basierte Beschreibungsdatei TwinCAT-spezifische Eigenschaften abbilden. Die XML gewährleistet einen erweiterten Funktionsumfang des TwinCAT Machine Learning-Produkts – siehe bspw. das Konzept der Multi-Engines. Andererseits stellt sie ein nahtloses Zusammenarbeiten zwischen Erzeuger und Anwender der Beschreibungsdatei sicher – vgl. Ein- und Ausgangstransformationen und Custom Attributes.

Im Folgenden werden wesentliche Bereiche der Beckhoff ML XML beschrieben. Dies dient dem Verständnis der darin bereitgestellten Funktionen.

XML Tag <MachineLearningModel>

Obligatorisches Tag mit 2 obligatorischen Attributen. Das Tag wird automatisch erzeugt und darf nicht manipuliert werden.

Beispiel:

<MachineLearningModel modelName="Support_Vector_Machine" defaultEngine="svm_fp64_engine">

Das Attribut modelName kann in der PLC ausgelesen werden über die Methode GetModelName. Über den Modellnamen wird der Modelltyp identifiziert, welcher geladen werden soll. Das Attribut kann z. B. die Werte support_vector_machine oder mlp_neural_network annehmen.

Das Attribut modelName in diesem Tag ist nicht zu verwechseln mit dem Attribut str_modelName aus <ModelDescription>.

XML Tag <CustomAttributes>

Das Tag CustomAttributes ist optional und kann vom Anwender frei genutzt werden. Die Tiefe des Baums und die Anzahl der Attribute ist nicht begrenzt. Die Erstellung kann über den TC3 Machine Learning Model Manager erfolgen. Ebenso kann die XML in diesem Bereich manuell editiert werden.

Attribute können in der PLC ausgelesen werden über die Methoden GetCustomAttribute_array, GetCustomAttribute_fp64, GetCustomAttribute_int64 und GetCustomAttribute_str. In der XML ist die Typisierung durch die Prefixe str_, int64_, fp64_ usw. gegeben.

Beispiel:

<CustomAttributes>
   <Model str_Name="TempEstimator" str_Version="1.2.11.0" />
   <MetaInfo arrfp64_InputRange="0.10000000000000001,0.90000000000000002" int64_TheAnswer="42" />
</CustomAttributes>

Hier wird ein Modell mit dem Namen „TempEstimator“ in der Version 1.2.11.0 angelegt. Als weiterführende Information wird ein Array und ein Integer Wert bereitgestellt. Exemplarischer Code zum Auslesen der CustomAttributes kann im Bereich Beispiele heruntergeladen werden.

XML Tag <AuxilliarySpecifications>

Der Bereich AuxilliarySpecifications ist optional und untergliedert in die Childs <PTI> und <IOModification>.

Beispiel:

<AuxiliarySpecifications>
   <PTI str_producer="Beckhoff MLlib Keras Exporter" str_producerVersion="3.0.200525.0 str_requiredVersion="3.0.200517.0d"/>
   <ModelDescription str_modelVersion="2.3.1.0" str_modelName="CurrentPreControlAxis42" str_modelDesc="This is the most awesome model to control Axis42" str_modelAuthor="Max" str_modelTags="awesome,ingenious,astounding" />
   <IOModification>
      <OutputTransformation str_type="SCALED_OFFSET" fp64_offsets="0.48288949404162623" fp64_scalings="1.4183887951105305"/>
   </IOModification>
</AuxiliarySpecifications>

<PTI>

PTI steht für „Product Version und Target Version Information“. Hier wird angegeben, mit welchem Werkzeug die XML erstellt wurde und welche Version das erstellende Werkzeug zum Zeitpunkt der XML-Erzeugung trug.

Ebenso kann, über das Attribut str_requiredVersion, eine Mindestversion der ausführenden ML Runtime angegeben werden. Ist das Attribut nicht gesetzt, gilt die Abfrage als bestanden. Ist das Attribut gesetzt, gilt die Abfrage als bestanden, wenn die ML Runtime Version größer oder gleich der required Version ist. Ist die Abfrage nicht bestanden, d. h. ist die genutzte Version der ML Runtime kleiner als die vorausgesetzte Version, wird bei Ausführung der Configure-Methode eine Warnung ausgegeben.

<IOModification>

Werden Eingänge oder Ausgänge des gelernten Modells in der Trainingsumgebung skaliert, können die genutzten Skalierungsparameter direkt in die XML-Datei integriert werden, sodass TwinCAT die Skalierung automatisch in der ML Runtime durchführt.

Die Skalierung erfolgt durch y = x * Scaling + Offset.

<ModelDescription>

Attribute an diesem optionalen Tag beschreiben

XML Tag <Configuration>

Der obligatorische Bereich Configuration beschreibt die Struktur des geladenen Modells.

Beispiel SVM

<Configuration str_operationType="SVM_TYPE_NU_REGRESSION" fp64_cost="0.1" fp64_nu="0.3" str_kernelFunction="KERNEL_FN_RBF" fp64_gamma="1.0" int64_numInputAttributes="1"/>

Beispiel MLP

<Configuration int_numInputNeurons="1" int_numLayers="2" bool_usesBias="true">
   <MlpLayer1 int_numNeurons="3" str_activationFunction="ACT_FN_TANH"/>
   <MlpLayer2 int_numNeurons="1" str_activationFunction="ACT_FN_IDENTITY"/>
</Configuration>

Eine Konfiguration existiert nur einmalig und wird automatisch generiert.

XML Tag <Paramaters>

Der obligatorische Bereich Parameters konkretisiert das geladene Modell mit der beschriebenen <Configuration>. Hier werden die gelernten Parameter des Modells abgelegt, z. B. die Gewichte der Neuronen.

Im Standardfall, d. h. es ist ein gelerntes Modell in einer XML beschrieben, ist der Tag <Parameters> nur einmal in der XML vorhanden. 

<Parameters str_engine="mlp_fp32_engine" int_numLayers="2" bool_usesBias="true">

Über den Machine Learning Model Manager können mehrere Modelle mit identischer <Configuration> zusammengeführt werden, sodass beide Modelle in einer einzelnen XML beschrieben sind. Die Parametersätze können dann durch die Engines unterschieden werden, welche als Attribut für jeden Parameter-Tag angegeben ist.

Beispiel:

<Parameters str_engine="mlp_fp32_engine::merge0" int64_numLayers="2" bool_usesBias="true">
   …
</Parameters>
<Parameters str_engine="mlp_fp32_engine::merge1" int64_numLayers="2" bool_usesBias="true">
   …
</Parameters>
<IODistributor str_distributor="multi_engine_io_distributor::mlp_fp32_engine-merge" str_engine_type="mlp_fp32_engine" int64_engine_count="2">
   <Engine0 str_engine_name="merge0" str_reference="sin_engine" />
   <Engine1 str_engine_name="merge1" str_reference="cos_engine" />
</IODistributor>

Hier wurden zwei MLPs mit identischer Configuration zusammengeführt. Die erste Engine trägt die ID 0, den internen Namen „mlp_fp32_engine::merge0“ und kann vom Nutzer über die Referenz „sin_engine“ angesprochen werden. Die zweite Engine trägt die ID 1, den internen Namen „mlp_fp32_engine::merge1“ und die Referenz „cos_engine“.

Die ID der Engines wird von Null angefangen fortlaufend um den Wert Eins erhöht. Die Referenz ist ein String, welcher im Model Manager beim Merge angegeben werden kann.

Werden mehrere Engines in einer XML zusammengefasst, werden alle Engines in der ML Runtime geladen und stehen zur Inferenz zur Verfügung. Der Predict-Methode ist beim Aufruf die Engine-ID zu übergeben, welche genutzt werden soll. Über die PredictRef-Methode kann die Referenz der Engine übergeben werden. Ebenso steht eine GetEngineIdFromRef-Methode zur Verfügung, um aus der Referenz die zugehörige ID zu finden. Ein Wechsel zwischen den Engines ist ohne Latenz möglich.

Ein Beispiel zur Nutzung von Multi-Engines in der PLC ist im Bereich Beispiele vorhanden.