Das könnte dich ebenfalls interessieren: Swagger zu Node Server hinzufügen

Schritt 1: NestJS auf Vercel hosten

Das Wichtigste zuerst: Die Grundeinstellungen für die Bereitstellung auf Vercel. Vercel ist großartig für Serverless, aber die Arbeit mit NestJS benötigt ein paar Anpassungen. Die Hauptsache ist, eine vercel.json-Konfigurationsdatei einzurichten, die Vercel genau sagt, wie die App zu behandeln ist.

Hier ist die Endkonfiguration:

{
  "version": 2,
  "builds": [
    {
      "src": "src/main.ts",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "src/main.ts",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "OPTIONS",
        "DELETE",
        "HEAD",
        "CONNECT",
        "TRACE"
      ]
    }
  ]
}

Ich habe daraufhin in Vercel folgende Fehlermeldung erhalten:

This Serverless Function has crashed. Your connection is working correctly. 
Vercel is working correctly. 500: INTERNAL_SERVER_ERROR 
Code: FUNCTION_INVOCATION_FAILED ID: bom1::sgk4v-1711014022883-1e9ed54f4c37

Bei einem Blick in die Logs stellte ich fest, dass die Datenbankverbindung ein Problem darstellte und außerdem die folgende Logmeldung angezeigt wurde:

No exports found in module "/var/task/app-name/src/main.js".
Did you forget to export a function or a server?

Es stellte sich heraus, dass ich den zweiten Teil der Fehlermeldung ignorieren und mich nur auf die Datenbankverbindung konzentrieren musste.

Schritt 2: Konfigurieren der Datenbank

Für meine Anwendung habe ich eine mysql-Datenbank mit mehreren Schemata verwendet. Ich habe mehrere kostenlose Angebote ausprobiert, aber sie waren nicht mit dem Ansatz mehrerer Schemata kompatibel. Daher habe ich mich für das Hosting bei Google Cloud entschieden. Ich habe es auf einen Preis von 0,01 $ pro Stunde heruntergeschraubt und das 300 $-Einsteigerangebot genutzt.

Um Vercel eine Verbindung zu ermöglichen, musste in der Konfiguration von Google Cloud die IP-Adresse auf 0.0.0.0/0 gesetzt werden, so dass die Datenbank von jeder IP-Adresse aus zugänglich war.

Schritt 3: Umgang mit CORS

Die CORS Fehler haben auch für einige Kopfschmerzen gesorgt. Stelle sicher, dass OPTIONS für CORS Preflight-Anfragen zugelassen wird, da Vercel eine explizite Erlaubnis für Cross-Origin-Anfragen benötigt. Am Ende musste ich eine Menge Header hinzufügen, um sicherzustellen, dass die Anfragen erlaubt waren:

app.enableCors({
    origin: 'domain-name',
    credentials: true,
    methods: 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',
    allowedHeaders: [
      'Origin',
      'X-Requested-With',
      'Content-Type',
      'Accept',
      'Authorization',
    ],
  });

Schritt 4: Umstellung auf express-session und Redis für die Sitzungsverwaltung

Einer der kniffligsten Teile war die Sessions zum Laufen zu bringen. Ich begann mit der cookie-session Bibliothek, aber Vercel ignoriert sie komplett. Nach einem Blick in die Dokumentation und einigem Ausprobieren wechselte ich zur express-session Bibliothek, da sie populärer ist und besser mit Vercels serverloser Umgebung funktioniert.

Aus irgendeinem Grund muss die Import-Syntax genau so aussehen:

import session = require('express-session');

Außerdem musste ich die Sitzungsmiddleware mit aktiviertem Vertrauensproxy konfigurieren, da Vercel Anfragen proxifiziert. So sieht die Einstellung aus:

const expressApp = app.getHttpAdapter().getInstance();
expressApp.set('trust proxy', true);

Auch die Einstellung secure: true und sameSite: ’none‘ war wichtig, um sicherzustellen, dass Cookies über HTTPS und verschiedene Domainanfragen funktionieren!

Beachten, dass mit Vercel mehrere serverlose Instanzen Anfragen bearbeiten können, was bei parallelen Anfragen leider zu Sitzungskonflikten führt. Um dies zu beheben, habe ich meinen Sitzungsspeicher mit einer Redis-Instanz verbunden. Glücklicherweise war das super einfach.

Redis hält die Sitzungsdaten konsistent und vermeidet Konflikte zwischen Anfragen, insbesondere unter Last. Hier der Code:

const expressApp = app.getHttpAdapter().getInstance();
expressApp.set('trust proxy', true);

const redisClient = createClient({
    password: process.env.REDIS_PASSWORD,
    socket: {
      host: process.env.REDIS_HOST,
      port: parseInt(process.env.REDIS_PORT, 10),
    },
  });

  redisClient
    .connect()
    .catch((err) =>
      console.log('Could not establish a connection with Redis: ' + err),
    );

  redisClient.on('error', (err) => console.log('Redis error: ' + err));
  redisClient.on('connect', () =>
    console.log('Connected to Redis successfully'),
  );

  app.use(
    session({
      store: new RedisStore({ client: redisClient }),
      secret: process.env.COOKIE_SECRET,
      cookie: {
        secure: process.env.NODE_ENV !== 'development',
        sameSite: process.env.NODE_ENV === 'development' ? 'lax' : 'none',
        maxAge: 86400000,
      },
    }),
  );

Schritt 5: Hinzufügen von withCredentials im Frontend

Dieser Schritt ist nur eine Randnotiz: Damit Session-Cookies zwischen Frontend und Backend funktionieren, muss withCredentials in den HTTP-Anfragen meines Frontends auf true gesetzt werden. Dies ermöglicht die Einbeziehung von Cookies in herkunftsübergreifende Anfragen, was wichtig ist, wenn das Frontend und das Backend getrennt gehostet werden. Ich musste sicherstellen, dass der HTTP-Client von Angular diese Einstellung aktiviert hat.

Schritt 6: Schriftart hinzufügen

Um Schriftdateien in Ihr NestJS-Projekt einzubinden, muss man die CompilerOptions in der nest-cli.json-Datei verwenden, um Assets für die Build-Ausgabe zu definieren, z. B. durch die Angabe von „include“: „**/*.ttf“ und ‚outDir‘: „dist/src“.

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "assets": [
      {
        "include": "**/*.ttf",
        "outDir": "dist/src"
      }
    ],
    "deleteOutDir": true
  }
}

Anschließend kann man nach dem Build die Schriftarten im Code mit path.resolve referenzieren, z. B. path.resolve(__dirname, ‚../fonts/Roboto-Regular.ttf‘). Auf diese Weise wird sichergestellt, dass die Schriftartendateien mit dem Build gebündelt werden und während der Laufzeit zugänglich sind.

Schlussgedanken zum Thema NestJS auf Vercel hosten

Das Deployment meiner NestJS-App auf Vercel war eine wahre Achterbahnfahrt. Manchmal hatte ich das Gefühl, dass ich kurz davor war, alles perfekt zum Laufen zu bringen, nur um dann mit neuen Fehlern konfrontiert zu werden, die mich zurück in den Fehlersuch-Modus schickten. Es gab Momente der Frustration – vor allem im Zusammenhang mit der Sessionverarbeitung und CORS-Problemen. Aber jede Lösung brachte ein neues Hoch, und jeder behobene Fehler fühlte sich wie ein kleiner Sieg an.

Jetzt, wo endlich alles reibungslos funktioniert, kann ich sagen, dass es ein großartiges Gefühl ist. Wenn ich sehe, dass meine Anwendung so funktioniert, wie ich es mir vorgestellt habe, ist das all die Kopfschmerzen wert. Es ist eine große Erleichterung, aber noch mehr freut es mich, zu wissen, dass ich jede Hürde überwunden habe und auf das, was ich gelernt habe, zurückblicken kann. Ich hoffe, dieser Leitfaden kann anderen einige dieser Schwierigkeiten ersparen und helfen, diesen „Es funktioniert einfach“-Moment etwas schneller zu erreichen!

The post Erfahrungen aus der Praxis: NestJS auf Vercel hosten appeared first on Nerd Corner.

Das könnte dich auch interessieren: NLP Anwendung Teil 1 (Daten einlesen, Daten vorbereiten und Tokenisierung)

OOV Token

Bei einem Übersetzer ist es nur eine Frage der Zeit bis ein unbekanntes Wort eingegeben wird. Das kann ein Eigenname, ein Rechtschreibfehler oder ähnliches sein. Es empfiehlt sich daher das Modell auch im Hinblick auf unbekannte Wörter zu trainieren. Hierfür wird ein OOV Token benötigt. OOV steht für „out of vocabulary“. Während des Trainings lernt das Modell, diesen Token zu erzeugen oder entsprechend zu behandeln. In diesem Fall kann ein unbekanntes Wort durch den Token „<oov>“ ersetzt werden, bevor es an das Modell übergeben wird. Das Modell wird es dann wie jedes andere Token behandeln und eine Antwort auf der Grundlage seines gelernten Verhaltens generieren.

Jetzt fragt man sich vielleicht wie inkludiert man diesen OOV Token in die Trainingsdaten? Ich mache das so, dass mein Datensatz zu Beginn automatisiert nach Wörtern durchsucht wird, die nur 1 Mal vorkommen. Diese seltenen Wörter ersetze ich dann durch „<oov>“, damit kann mein Modell lernen auch unbekannte Wörter zu reagieren.

Padding

Bei vielen Modellen des maschinellen Lernens, einschließlich neuronaler Netze, wird erwartet, dass die Eingaben eine feste Größe oder Form haben. Diese Anforderung ergibt sich aus der Struktur und dem Betrieb des zugrunde liegenden Berechnungsgraphen. Eingaben mit derselben Länge vereinfachen die Datenverarbeitungspipeline und ermöglichen eine effiziente Stapelverarbeitung.

Warum die Eingaben gleich lang sein sollten:

1. Matrix-Operationen: Neuronale Netze verarbeiten Eingaben in der Regel in Stapeln, und die Stapelverarbeitung ist am effizientesten, wenn die Eingabedaten eine einheitliche Form haben. Die Daten sind in Matrizen organisiert, wobei jede Zeile eine Eingabeinstanz darstellt. Um Matrixoperationen effizient durchführen zu können, müssen alle Eingabeinstanzen die gleiche Form haben.
2. Gemeinsame Nutzung von Parametern: In vielen neuronalen Netzwerkarchitekturen werden die Modellparameter (Gewichte) auf verschiedene Teile der Eingabesequenz verteilt. In rekurrenten neuronalen Netzen (RNNs) werden beispielsweise dieselben Gewichte für die Verarbeitung jedes Zeitschritts verwendet. Um die gemeinsame Nutzung von Parametern zu ermöglichen, müssen alle Eingabesequenzen die gleiche Länge haben.
3. Speicherzuweisung: Neuronale Netze weisen den Speicher oft auf der Grundlage der maximalen Länge der Eingabesequenzen zu. Wenn die Sequenzen unterschiedliche Längen haben, ist eine dynamische Speicherzuweisung erforderlich, die komplexer und weniger effizient sein kann.

Es ist zwar möglich, Eingaben mit variabler Länge durch Techniken wie Auffüllen und Maskieren zu verarbeiten, aber dies erhöht die Komplexität des Modells und kann zusätzliche Verarbeitungsschritte erfordern. Der Einfachheit und Effizienz halber ist es daher üblich, Sequenzen auf eine feste Länge aufzufüllen oder abzuschneiden, bevor sie in ein neuronales Netzmodell eingespeist werden.

from keras.utils import pad_sequences

# pad sequences
encoder_seq = pad_sequences(encoder, maxlen=max_encoder_sequence_len, padding="post")
decoder_inp = pad_sequences([arr[:-1] for arr in decoder], maxlen=max_decoder_sequence_len, padding="post")
decoder_output = pad_sequences([arr[1:] for arr in decoder], maxlen=max_decoder_sequence_len, padding="post")
print(encoder_seq)
print([idx_2_txt_encoder[i] for i in encoder_seq[0]])
print([idx_2_txt_decoder[i] for i in decoder_inp[0]])
print([idx_2_txt_decoder[i] for i in decoder_output[0]])

Zur besseren Veranschaulichung habe ich die 4 print Befehle hinzugefügt. Anfangs dachte ich, dass der längste Satz im Datensatz die Länge für Input Daten und Output Daten vorgibt. Also die Paddinglänge für Input und Output gleich wäre. Das ist aber nicht der Fall! Input Daten und Output Daten sind auf unterschiedliche Längen normiert!

In dem Beispiel hier, habe ich einen winzigen Datensatz benutzt bei dem der längste englische Satz aus 3 Wörtern besteht und der längste französische Satz aus 10 Wörtern. Demnach wird mit „<pad>“ bzw 0 jeder Trainingssatz aufgefüllt bis der Input 3 bzw. der Output 10 Wörter erreicht hat.

Der Decoder Output mit [arr[1:] for arr in decoder] entfernt den „start“ token und der Decoder Input mit [arr[:-1] for arr in decoder] entfernt den „end“ token.

Bei Sequenz-zu-Sequenz-Modellen wird der Decoder darauf trainiert, die Ausgabesequenz auf der Grundlage der Eingabesequenz und der zuvor generierten Token zu erzeugen. Während des Trainings enthält die Eingangssequenz des Decoders den „Start“-Token, der als Initialisierungs-Token für den Decoder dient. Beim Training des Decoders soll dieser jedoch den nächsten Token auf der Grundlage der zuvor generierten Token vorhersagen, mit Ausnahme des „Start“-Tokens. Daher wird bei der Vorbereitung der Decoder-Ausgabesequenz das „Start“-Token aus jeder Sequenz entfernt. Dies geschieht, um die Eingangs- und Ausgangssequenzen des Decoders korrekt aufeinander abzustimmen. Die Decoder-Eingangssequenz enthält den „Start“-Token und schließt den „End“-Token aus, während die Decoder-Ausgangssequenz den „End“-Token enthält und den „Start“-Token ausschließt. Auf diese Weise stellen wir sicher, dass der Decoder lernt, die richtige Ausgabesequenz auf der Grundlage der Eingabe zu erzeugen.

Während der Inferenz (Modellanwendung nach dem Training) bzw. der Übersetzung können wir bei der Verwendung des trainierten Modells zur Erzeugung von Übersetzungen mit dem „Start“-Token beginnen und iterativ Token erzeugen, bis wir auf das „End“-Token stoßen oder eine maximale Sequenzlänge erreichen.

Beim Padding für Tensorflow.js übernehmen wir 1:1 die Vorgehensweise von Python. Leider haben wir auch hier wieder mehr Arbeit und mehr Code Zeilen, da in Tfjs keine padSequences Funktion existiert. Ich habe mir deswegen eine eigene padSequences Funktion geschrieben:

function padSequences(sequences) {
  const paddedSequences = [];
  const maxlen = findMaxLength(sequences);

  for (const sequence of sequences) {
    if (sequence.length >= maxlen) {
      paddedSequences.push(sequence.slice(0, maxlen));
    } else {
      const paddingLength = maxlen - sequence.length;
      const paddingArray = new Array(paddingLength).fill(0);
      const paddedSequence = sequence.concat(paddingArray);
      paddedSequences.push(paddedSequence);
    }
  }

  return paddedSequences;
}

Anschließend können wir mit Hilfe dieser Funktion unseren encoder, decoder Input und decoder Output bestimmen:

function pad(data) {
  const encoderSeq = padSequences(data.en);
  const decoderInp = padSequences(data.de.map((arr) => arr.slice(0, -1))); // Has startToken
  const decoderOutput = padSequences(data.de.map((arr) => arr.slice(1))); // Has endToken
  console.log(decoderInp);
}

Bei mir ist die „1“ der „startToken“ daher sieht der decoder Input beispielsweise so aus:

Modell erstellen

# Design LSTM NN (Encoder & Decoder)
# encoder model
encoder_input = Input(shape=(None,), name="encoder_input_layer")
encoder_embedding = Embedding(num_encoder_tokens, 300, input_length=max_encoder_sequence_len, name="encoder_embedding_layer")(encoder_input)
encoder_lstm = LSTM(256, activation="tanh", return_sequences=True, return_state=True, name="encoder_lstm_1_layer")(encoder_embedding)
encoder_lstm2 = LSTM(256, activation="tanh", return_state=True, name="encoder_lstm_2_layer")(encoder_lstm)
_, state_h, state_c = encoder_lstm2
encoder_states = [state_h, state_c]

# decoder model
decoder_input = Input(shape=(None,), name="decoder_input_layer")
decoder_embedding = Embedding(num_decoder_tokens, 300, input_length=max_decoder_sequence_len, name="decoder_embedding_layer")(decoder_input)
decoder_lstm = LSTM(256, activation="tanh", return_state=True, return_sequences=True, name="decoder_lstm_layer")
decoder_outputs, _, _ = decoder_lstm(decoder_embedding, initial_state=encoder_states)
decoder_dense = Dense(num_decoder_tokens+1, activation="softmax", name="decoder_final_layer")
outputs = decoder_dense(decoder_outputs)

model = Model([encoder_input, decoder_input], outputs)

Das Codebeispiel zeigt den  Entwurf eines neuronalen Netzes mit Long Short-Term Memory (LSTM) für Sequenz-zu-Sequenz-Lernen (Seq2Seq) dar, das typischerweise für Aufgaben wie maschinelle Übersetzung verwendet wird. Der Code definiert zwei Hauptteile:  Encoder-Modell und Decoder-Modell.

Encoder-Modell:

• • Die Encoder-Eingangsschicht (encoder_input) stellt die Eingangssequenz des Encoder-Modells dar.
  • Die Eingangssequenz wird mithilfe einer Einbettungsschicht (encoder_embedding) eingebettet, die jedes Token in eine dichte Vektordarstellung umwandelt.
  • Die eingebettete Sequenz wird dann durch die erste LSTM-Schicht (encoder_lstm_1_layer) geleitet, um sequenzielle Informationen zu erfassen. Die LSTM-Schicht gibt die Ausgabesequenz und den endgültigen versteckten Zustand zurück.
  • Die Ausgabesequenz der ersten LSTM-Schicht wird von der zweiten LSTM-Schicht (encoder_lstm_2_layer) weiterverarbeitet. Die zweite LSTM-Schicht liefert nur den endgültigen versteckten Zustand, der die zusammengefasste Information der Eingabesequenz darstellt.
  • Der final hidden Zustand der zweiten LSTM-Schicht wird in den final hidden Zustand (state_h) und den final Zellzustand (state_c) aufgeteilt, die als Anfangszustände für das Decodermodell verwendet werden.
  • Die Zustände des Encoder-Modells sind als encoder_states definiert und werden an das Decoder-Modell weitergegeben.

Decoder-Modell:

• Die Decoder-Eingangsschicht (decoder_input) stellt die Eingangssequenz des Decoder-Modells dar, die aus der um eine Position verschobenen Zielsequenz besteht.
• Ähnlich wie beim Encoder wird die Eingangssequenz mit Hilfe einer Einbettungsschicht (decoder_embedding) eingebettet.
• Die eingebettete Sequenz wird dann durch eine LSTM-Schicht (decoder_lstm_layer) geleitet, wobei die Anfangszustände auf die Endzustände des Encoder-Modells gesetzt werden. Dies ermöglicht es dem Decoder, die relevanten Informationen des Encoders zu berücksichtigen.
• Die LSTM-Schicht liefert die Ausgabesequenz und die Endzustände.
• Die Ausgabesequenz aus der LSTM-Schicht wird durch eine dichte Schicht (decoder_final_layer) mit einer Softmax-Aktivierungsfunktion geleitet, die die Wahrscheinlichkeitsverteilung über die ausgegebenen Token vorhersagt.

Die Klasse Model wird zur Erstellung des Gesamtmodells verwendet, indem die Eingabeschichten ([encoder_input, decoder_input]) und die Ausgabeschicht (outputs) angegeben werden. Diese Modellarchitektur folgt der Grundstruktur eines Encoder-Decoder-Modells unter Verwendung von LSTMs, bei dem der Encoder die Eingabesequenz verarbeitet und den Kontextvektor (final hidden state) erzeugt, der dann vom Decoder zur Erzeugung der Ausgabesequenz verwendet wird.

Das selbe Modell lässt sich auch in JS umsetzen:

function createModell(
  numEncoderTokens,
  numDecoderTokens,
  maxEncoderSequenceLen,
  maxDecoderSequenceLen
) {
  // Encoder model
  const encoderInput = tf.input({ shape: [null], name: "encoderInputLayer" });
  const encoderEmbedding = tf.layers
    .embedding({
      inputDim: numEncoderTokens,
      outputDim: 300,
      inputLength: maxEncoderSequenceLen,
      name: "encoderEmbeddingLayer",
    })
    .apply(encoderInput);
  const encoderLstm = tf.layers
    .lstm({
      units: 256,
      activation: "tanh",
      returnSequences: true,
      returnState: true,
      name: "encoderLstm1Layer",
    })
    .apply(encoderEmbedding);
  const [_, state_h, state_c] = tf.layers
    .lstm({
      units: 256,
      activation: "tanh",
      returnState: true,
      name: "encoderLstm2Layer",
    })
    .apply(encoderLstm);
  const encoderStates = [state_h, state_c];

  // Decoder model
  const decoderInput = tf.input({ shape: [null], name: "decoderInputLayer" });
  const decoderEmbedding = tf.layers
    .embedding({
      inputDim: numDecoderTokens,
      outputDim: 300,
      inputLength: maxDecoderSequenceLen,
      name: "decoderEmbeddingLayer",
    })
    .apply(decoderInput);
  const decoderLstm = tf.layers.lstm({
    units: 256,
    activation: "tanh",
    returnState: true,
    returnSequences: true,
    name: "decoderLstmLayer",
  });
  const [decoderOutputs, ,] = decoderLstm.apply(decoderEmbedding, {
    initialState: encoderStates,
  });
  const decoderDense = tf.layers.dense({
    units: numDecoderTokens + 1,
    activation: "softmax",
    name: "decoderFinalLayer",
  });
  const outputs = decoderDense.apply(decoderOutputs);

  const model = tf.model({ inputs: [encoderInput, decoderInput], outputs });
  return model;
}

Modell trainieren und speichern

# train model
loss = tf.losses.SparseCategoricalCrossentropy()
model.compile(optimizer='rmsprop', loss=loss, metrics=['accuracy'])
callback = tf.keras.callbacks.EarlyStopping(monitor='loss', patience=3)
history = model.fit(
   [encoder_seq, decoder_inp],
   decoder_output,
   epochs=80,  # 80
   batch_size=450,  # 450
   # callbacks=[callback]
)

Die Funktion model.fit() wird zum Trainieren des Modells verwendet. Die Trainingsdaten bestehen aus den Encoder-Eingangssequenzen (encoder_seq), den Decoder-Eingangssequenzen (decoder_inp) und den Decoder-Ausgangssequenzen (decoder_output). Das Training wird für eine bestimmte Anzahl von Epochen (epochs) und eine Batchgröße von 450 durchgeführt. Der Trainingsfortschritt kann mit dem EarlyStopping-Callback überwacht werden, der das Training abbricht, wenn sich der Verlust nach einer bestimmten Anzahl von Epochen nicht verbessert hat. Der Trainingsverlauf wird in der Variable history gespeichert.

Das Modell in Tensorflow kann sowohl Tensoren als auch Numpy-Arrays als Eingaben verarbeiten. Wenn man Numpy-Arrays als Eingaben an die Funktion fit in TensorFlow übergibt, konvertiert diese sie intern automatisch in Tensoren, bevor das Training durchgeführt wird. Im Code werden die encoder_seq, decoder_inp und decoder_output Arrays automatisch in Tensoren umgewandelt, wenn man sie an die fit Funktion übergibt. Dies erlaubt es TensorFlow, die notwendigen Berechnungen während des Trainingsprozesses durchzuführen.

In ähnlicher Weise kann die Funktion fit in TensorFlow.js sowohl mit Tensoren als auch mit Arrays umgehen. Man kann also direkt sein 2D-Array (encoderSeq) als erste Eingabe übergeben und TensorFlow.js wird sie intern in Tensoren für das Training umwandeln. Obwohl man Arrays anstelle von Tensoren übergibt, sind TensorFlow und TensorFlow.js in der Lage, die Konvertierung intern zu handhaben und das Training entsprechend durchzuführen.

# save model
model.save("./model-experimental/Translate_Eng_FR.h5")
model.save_weights("./model-experimental/model_NMT")

Es ist üblich, die Gewichte eines trainierten Modells getrennt von der Modellarchitektur zu speichern. Die separate Speicherung der Gewichte und der Architektur ermöglicht mehr Flexibilität beim Laden und Verwenden des Modells. So kann man beispielsweise nur die Gewichte laden, wenn die Modellarchitektur an anderer Stelle definiert wurde oder wenn die Gewichte in einem anderen Modell mit einer ähnlichen Architektur verwenden werden sollen.

Abschließend auch der Code in JavaScript:

async function trainModel(data) {
  const encoderSeq = padSequences(data.en);
  const decoderInp = padSequences(data.de.map((arr) => arr.slice(0, -1))); // Has startToken
  const decoderOutput = padSequences(data.de.map((arr) => arr.slice(1))); // Has endToken

  data.model.compile({
    optimizer: "rmsprop",
    loss: "sparseCategoricalCrossentropy",
    metrics: ["accuracy"],
  });
  const history = await data.model.fit(
    [encoderSeq, decoderInp],
    decoderOutput,
    {
      epochs: 80,
      batch_size: 450,
    }
  );
}

An dieser Stelle kommt meine Frustration mit Tensorflow.js ins Spiel. Obwohl jeder Schritt 1:1 dem Schritt in Python entspricht klappt das Training des Modells in Tensorflow.js nicht… Ich erhalte immer eine Fehlermeldung:

C:\Users\[...]\node_modules\@tensorflow\tfjs-layers\dist\tf-layers.node.js:23386
            if (array.shape.length !== shapes[i].length) {
                            ^

TypeError: Cannot read properties of undefined (reading 'length')
    at standardizeInputData

Allgemein Verlustfunktion und Optimierer

Verlustfunktionen und Optimierer sind Schlüsselkomponenten beim Training eines maschinellen Lernmodells. Eine Verlustfunktion, die auch als Ziel- oder Kostenfunktion bezeichnet wird, misst die Leistung eines Modells, indem sie die Unähnlichkeit zwischen den vorhergesagten Ausgaben und den tatsächlichen Zielen quantifiziert. Das Ziel des Trainings eines Modells ist es, diese Verlustfunktion zu minimieren, was im Wesentlichen bedeutet, dass die Fähigkeit des Modells, genaue Vorhersagen zu treffen, verbessert wird. Die Wahl der Verlustfunktion hängt von der jeweiligen Problemstellung ab. Bei Klassifizierungsaufgaben sind beispielsweise die kategoriale Kreuzentropie, die binäre Kreuzentropie und die Softmax-Kreuzentropie gängige Verlustfunktionen, während bei Regressionsaufgaben häufig der mittlere quadratische Fehler (MSE) und der mittlere absolute Fehler (MAE) verwendet werden.

Ein Optimierer hingegen ist für die Aktualisierung der Modellparameter (Gewichte und Verzerrungen) während des Trainings verantwortlich, um die Verlustfunktion zu minimieren. Er bestimmt, wie die Parameter des Modells auf der Grundlage der berechneten Gradienten der Verlustfunktion in Bezug auf diese Parameter angepasst werden. Optimierer verwenden verschiedene Algorithmen und Techniken, um effizient nach den optimalen Werten der Parameter zu suchen. Zu den gängigen Optimierern gehören Stochastic Gradient Descent (SGD), Adam, RMSprop und Adagrad. Jeder Optimierer hat seine eigenen Merkmale und Hyperparameter, die den Trainingsprozess und die Konvergenzgeschwindigkeit des Modells beeinflussen können.

Die Wahl der Verlustfunktion und des Optimierers hängt von der spezifischen Aufgabe, der Modellarchitektur und den Eigenschaften des Datensatzes ab. Es ist wichtig, geeignete Verlustfunktionen und Optimierer auszuwählen, um ein effektives Modelltraining und eine Konvergenz zur optimalen Leistung zu gewährleisten.

Häufig verwendete Verlustfunktionen und Optimierer

Verlustfunktionen:

• Kategoriale Kreuz-Entropie: Diese Verlustfunktion wird häufig in Sequenz-zu-Sequenz-Modellen für Mehrklassen-Klassifizierungsprobleme verwendet, bei denen jedes Zielwort als eine eigene Klasse behandelt wird.
•  Spärliche kategoriale Kreuzentropie: Ähnlich wie die kategoriale Kreuzentropie, aber geeignet, wenn die Zielsequenzen als spärliche ganzzahlige Sequenzen dargestellt werden (z. B. unter Verwendung von Wortindizes).

Optimierer:

• Adam: Adam ist ein beliebter Optimierer, der die Vorteile des Adaptiven Gradientenalgorithmus (AdaGrad) und der Root Mean Square Propagation (RMSprop) kombiniert. Er passt die Lernrate für jeden Parameter auf der Grundlage früherer Gradienten an, was zu einer schnelleren Konvergenz und einer besseren Handhabung spärlicher Gradienten beiträgt.
• RMSprop: RMSprop ist ein Optimierer, der einen gleitenden Durchschnitt der quadrierten Gradienten für jeden Parameter beibehält. Er passt die Lernrate auf der Grundlage der Größe des Gradienten an, was eine schnellere Konvergenz und eine bessere Leistung bei nicht stationären Zielen ermöglicht.
• Adagrad: Adagrad passt die Lernrate individuell für jeden Parameter an, basierend auf der historischen Gradientenakkumulation. Es führt größere Updates für seltene Parameter und kleinere Updates für häufige Parameter durch.

Dateien zum Herunterladen

• NLP Tensorflow.js code (model has an error!)

The post NLP Anwendung: Tensorflow.js vs Tensorflow Python – Teil 2 appeared first on Nerd Corner.

Ich habe viele Abende damit verbracht mein Projekt mit Tensorflow.js zum Laufen zu bringen und bin am Ende gescheitert. Der Wechsel auf Python brachte dann den erhofften Durchbruch! Ich würde jedem empfehlen für NLP Anwendungen Python zu nutzen! Nichtsdestotrotz möchte ich in diesem Beitrag einmal die Unterschiede zwischen Tensorflow.js und Tensorflow im Bezug auf mein Projekt anhand von Codebeispielen verdeutlichen. Zwischendurch werde ich auch so gut wie möglich mein neu angesammeltes Wissen in die jeweiligen Abschnitte einbauen.

Das könnte dich auch interessieren: NLP Anwendung Teil 2 (OOV Token, Padding, Modell erstellen und Modell trainieren)

Daten einlesen

Zunächst einmal braucht man einen Datensatz mit dem später das Modell trainiert werden soll. Hier kann ich https://www.kaggle.com/ empfehlen. Man findet dort eine Vielzahl an Datensätzen zur freien Verfügung und teilweise sogar weiterführende Codebeispiele. Den Datensatz kann man entweder per Link einlesen oder downloaden und dann lokal vom File System einlesen. Ein guter Datensatz sollte über 100.000 Beispiele enthalten. Am besten auch teilweise ganze Paragraphen. So sieht beispielsweise ein Englisch/Französischer Datensatz als CSV aus:

Zunächst die simple Variante mittels Python:

import pandas as pd

# read in dataSet for training
df = pd.read_csv("./dataset/eng_-french.csv")
df.columns = ["english", "french"]
print(df.head())
print(df.info())

Wir nutzen die pandas Library und lesen damit die CSV ein. Mit dem head() können wir testen ob es funktioniert hat und uns die ersten 5 Zeilen anzeigen lassen. Mittels info() erhalten wir weitere Infos wie beispielsweise Anzahl der Spalten und Anzahl der Reihen:

Zum Vergleich in Tensorflow.js (Tfjs) gibt es auch eine Möglichkeit CSV einzulesen:

const tf = require("@tensorflow/tfjs");

async function readInData() {
  await tf.ready();
  const languageDataSet = tf.data.csv("file://" + "./ger_en_trans.csv");

  // Extract language pairs
  const dataset = languageDataSet.map((record) => ({
    en: record.en,
    de: record.de,
  }));

  const pairs = await dataset.toArray();

  console.log(pairs);
}

readInData();

Ich habe dabei zunächst versucht den gleichen Datensatz wie in der Python Version einzulesen:

Anschließend wollte ich die Überschriften kürzen in der originalen CSV, dadurch bekam ich aber seltsamer Weise eine Fehlermeldung beim Einlesen. Selbst als ich den Originalzustand der CSV wiederhergestellt hatte, blieb der Fehler:

Letztlich habe ich mich dann dafür entschieden einen anderen Datensatz zu nutzen:

Der war beim Einlesen auch wesentlich besser lesbar:

Und hier das Endergebnis nach dem Mapping:

Obwohl Tfjs extra eine Funktion zum Einlesen der CSV bietet, hatte ich trotzdem schon mehr Ärger als in der Python Version. Ich habe auch auf die Schnelle keine Möglichkeit gefunden einen Datensatz im txt-Format einzulesen. Allerdings sind txt-Datensätze weit verbreitet!

Daten vorbereiten

Ich habe oft gesehen, dass für die Datenvorbereitung eine cleaning Funktion geschrieben wurde und der Output Satz auch einen Start und End Token erhalten hat. Daraufhin habe ich mich gefragt ob auch der Input Satz also der Encoder einen Start und End Token braucht. Im Rahmen von Sequenz-zu-Sequenz-Modellen benötigt der Encoder aber keine expliziten Start- und End-Token. Sein Zweck ist es, die Eingabesequenz so zu verarbeiten, wie sie ist, und eine Darstellung der Eingabe zu erstellen.

Der Decoder hingegen, der die Ausgabesequenz erzeugt, profitiert in der Regel von der Verwendung von Start- und End-Tokens. Diese Token helfen, den Anfang und das Ende der erzeugten Sequenz zu kennzeichnen. Die Verwendung von Start- und End-Token ist daher spezifisch für den Decoder. Während des Trainings enthält die Eingangssequenz des Decoders ein Start-Token am Anfang und schließt ein End-Token am Ende aus. Die Ausgabesequenz des Decoders enthält den End-Token und schließt den Start-Token aus. Auf diese Weise lernt das Modell, die richtige Ausgabesequenz auf der Grundlage der Eingabe zu erzeugen.

Bei der Erstellung von Übersetzungen mit dem trainierten Modell beginnt man mit dem Start-Token und generiert ein Token nach dem anderen, bis man auf den End-Token trifft oder eine maximale Sequenzlänge erreicht. Das Hinzufügen von Start- und End-Token zum Decoder-Satz verbessert die Leistung des NLP-Übersetzermodells. Es hilft bei der Festlegung klarer Sequenzgrenzen und unterstützt den Generierungsprozess, indem es angibt, wo die Übersetzung beginnt und endet.

Zusammengefasst:

• Encoder: Keine Notwendigkeit für Start- und End-Token. Verarbeitet die Eingabesequenz wie sie ist.
• Decoder: Start- und End-Token sind hilfreich für die Generierung der Ausgabesequenz.

Wir beginnen wieder mit dem einfachen Teil, nämlich Python. Wie wollen die eingelesenen Daten säubern. Das bedeutet alles in Kleinbuchstaben umwandeln und Zeichen, die nicht zum Alphabet gehören oder Satzzeichen sind, entfernen. Dafür brauchen wir die Regex Bibliothek (re).

import re

def clean(text):
    text = text.lower()  # lower case
    # remove any characters not a-z and ?!,'
    # please note that french has additional characters...I just simplified that
    text = re.sub(u"[^a-z!?',]", " ", text)
    return text


# apply cleaningFunctions to dataframe
data["english"] = data["english"].apply(lambda txt: clean(txt))
data["french"] = data["french"].apply(lambda txt: clean(txt))

# add <start> <end> token to decoder sentence (french)
data["french"] = data["french"].apply(lambda txt: f"<start> {txt} <end>")

print(data.sample(10))

Ich habe hier vereinfacht. Da es sich um einen französischen Datensatz handelt sollte man eigentlich eine extra cleaning Funktion schreiben, die auch französische Buchstaben wie „ê“ berücksichtigt. Die  sample() Funktion dient nur zum veranschaulichen der Daten:

In Tfjs ist der Ablauf absolut identisch. Ich habe eine cleanData() Funktion erstellt und den vorherigen Code modifiziert:

function cleanData(text) {
  //if necessary also remove any characters not a-z and ?!,'
  return text.toLowerCase();
}

const dataset = languageDataSet.map((record) => ({
   en: cleanData(record.en),
   de: "startToken " + cleanData(record.de) + " endToken",
 }));

Das Ergebnis ist daher auch identisch zum Python Ansatz:

Wenn die Wörter „start“ und „end“ Teil regulärer Sätze sind und nicht als spezielle Token zur Markierung von Anfang und Ende von Sequenzen verwendet werden, dann sollten sie bei der Tokenisierung auf keinen Fall durch entsprechende Indizes ersetzt werden. Bei der Tokenisierung ist es wichtig, spezielle Token zu wählen, die in den eigentlichen Eingabedaten wahrscheinlich nicht vorkommen werden. Dadurch wird sichergestellt, dass das Modell sie von normalen Wörtern unterscheiden kann und lernt, die entsprechenden Ausgabesequenzen zu erzeugen.

Wenn die Wörter “ start“ und „end“ reguläre Wörter in den Eingabesätzen sind, sollte man in Erwägung ziehen, verschiedene spezielle Token zu verwenden, um den Anfang und das Ende von Sequenzen zu markieren. Eine gängige Wahl sind “ <start>“ und „<end>“. Durch die Verwendung spezieller Token, die wahrscheinlich nicht zum regulären Vokabular gehören, kann sichergestellt werden, dass sie vom Modell während des Trainings und der Generierung richtig identifiziert und verarbeitet werden können.

Beispielsweise würden die tokenisierten Sequenzen wie folgt aussehen:

Decoder Eingabe: [„<start>“, „hallo“, „welt“]
Decoder Ausgabe: [„hallo“, „welt“, „<end>“]

Daher nachfolgendes VERMEIDEN:

Decoder Eingabe: [„start“, „hallo“, „welt“]
Decoder Ausgabe: [„hallo“, „welt“, „end“]

Tokenisierung

# tokenization
import tensorflow as tf
from tensorflow import keras
from keras.preprocessing.text import Tokenizer
import numpy as np

# english tokenizer
english_tokenize = Tokenizer(filters='#$%&()*+,-./:;<=>@[\\]^_`{|}~\t\n')
english_tokenize.fit_on_texts(data["english"])
num_encoder_tokens = len(english_tokenize.word_index)+1
# print(num_encoder_tokens)
encoder = english_tokenize.texts_to_sequences(data["english"])
# print(encoder[:5])
max_encoder_sequence_len = np.max([len(enc) for enc in encoder])
# print(max_encoder_sequence_len)

# french tokenizer
french_tokenize = Tokenizer(filters="#$%&()*+,-./:;<=>@[\\]^_`{|}~\t\n")
french_tokenize.fit_on_texts(data["french"])
num_decoder_tokens = len(french_tokenize.word_index)+1
# print(num_decoder_tokens)
decoder = french_tokenize.texts_to_sequences(data["french"])
# print(decoder[:5])
max_decoder_sequence_len = np.max([len(dec) for dec in decoder])
# print(max_decoder_sequence_len)

Dieser Code führt Tokenisierung und Sequenzvorverarbeitung mit der Tokenizer Klasse in TensorFlow durch.

1. english_tokenize = Tokenizer(filters=’#$%&()*+,-./:;<=>@[\\]^_`{|}~\t\n‘) Initialisiert ein Tokenizer-Objekt für englische Sätze. Der Parameter `filters` gibt Zeichen an, die während der Tokenisierung herausgefiltert werden sollen. Wir haben die Daten im Cleaning Prozess bereits gefiltert, es ist daher eigentlich nicht notwendig hier nochmal zu filtern.
2. english_tokenize.fit_on_texts(data[„english“]) Aktualisiert das interne Vokabular des Tokenizers basierend auf den englischen Sätzen in der Variable data. Jedem Wort im Vokabular wird ein eindeutiger Index zugewiesen.
3. num_encoder_tokens = len(english_tokenize.word_index) + 1 Bestimmt die Anzahl der eindeutigen Token (Wörter) im englischen Vokabular. Das Attribut word_index des Tokenizers gibt ein Wörterbuch zurück, das Wörter auf ihre jeweiligen Indizes abbildet.
4. encoder = english_tokenize.texts_to_sequences(data[„english“]) Konvertiert die englischen Sätze in der Variablen data in Sequenzen von Token-Indizes unter Verwendung des Tokenizers. Jeder Satz wird durch eine Folge von Ganzzahlen ersetzt, die die entsprechenden Wörter darstellen.
5. max_encoder_sequence_len = np.max([len(enc) for enc in encoder]) Berechnet die maximale Länge (Anzahl der Token) unter allen kodierten Sequenzen. Sie verwendet die Funktion max von NumPy, um den maximalen Wert in einem Listenverständnis zu finden.

Diese Schritte helfen, die Sätze für die weitere Verarbeitung in einem NLP-Modell vorzubereiten. Das ist für beide Sprachen notwendig!

Die Sätze wurden jetzt in Token umgewandelt, anschließend in Sequenzen von Token-Indizes konvertiert und die maximale Sequenzlänge bestimmt. Ein Beispielsatz aus dem Datensatz sieht jetzt so aus: [[148], [252], [59], [14], [111]]. Hierbei könnte die 148 für „I“, 252 für „am“, 59 für „very“, 14 für „hungry“ und 111 für „now“ stehen.

idx_2_txt_decoder = {k: i for i, k in french_tokenize.word_index.items()}
# print(idx_2_txt_decoder)
idx_2_txt_encoder = {k: i for i, k in english_tokenize.word_index.items()}
# print(idx_2_txt_encoder)

idx_2_txt_decoder[0] = "<pad>"
idx_2_txt_encoder[0] = "<pad>"

Der Codeschnipsel idx_2_txt_encoder = {k: i for i, k in english_tokenize.word_index.items()} erstellt ein Wörterbuch Verzeichnis idx_2_txt_encoder, das Token-Indizes den entsprechenden Wörtern im englischen Vokabular zuordnet: {k: i for i, k in english_tokenize.word_index.items()} ist ein Verzeichnis, das über die Schlüssel-Wert-Paare in english_tokenize.word_index iteriert. Bei jeder Iteration steht der Key (k) für ein Wort im Vokabular, und der Wert (i) für den entsprechenden Index. Das Verständnis erstellt ein neues Wörterbuch, dessen Keys die Indizes (i) und die Werte die Wörter (k) sind.

Das resultierende idx_2_txt_encoder – Wörterbuch ermöglicht es, das Wort, das einem bestimmten Index entspricht, im englischen Wortschatz nachzuschlagen. english_tokenize.word_index würde übrigens die Anzeigen genau vertauschen. Hier wäre der Key das Wort sein und der Wert der Index. Die zweite Zeile, idx_2_txt_encoder[0] = „<pad>“, fügt dem Wörterbuch einen speziellen Eintrag hinzu. Hier wird das Wort „<pad>“ dem Index „0“ zugeordnet, um einen Auffüllungs-Token anzugeben, der beim Padding von Sequenzen verwendet wird.

Anschließend sollte man das Wörterbuch Verzeichnis abspeichern, denn später wenn das Modell trainiert wurde und eingesetzt wird, werden die Übersetzungen des Modells ebenfalls eine Reihe von Indizes sein, die mit Hilfe des Wörterbuchs in lesbare Sätze zurücktransformiert werden.

# Saving the dicitionaries
pickle.dump(idx_2_txt_encoder, open("./saves/idx_2_word_input.txt", "wb"))
pickle.dump(idx_2_txt_decoder, open("./saves/idx_2_word_target.txt", "wb"))

Der gleiche Ablauf wie in Python lässt sich auch für die NLP Anwendung in Tensorflow.js konstruieren. Selbstverständlich benötigt man etwas mehr Codezeilen und der Arbeitsaufwand ist insgesamt höher. Die erste Hürde hierbei ist der Tokenizer. Leider besitzt Tfjs im Gegensatz zu Tensorflow (Python) keinen eigenen Tokenizer. Nach ausgiebiger Recherche fand ich zum Glück den natural.WordTokenizer. Hierbei möchte ich darauf hinweisen, dass definitv ein Node.js Projekt benötigt wird. Tfjs lässt sich zwar über einen <script> Tag einbinden, der natural.WordTokenizer, dagegen aber nicht!

Ein weiterer wichtiger Punkt ist, dass der WordTokenizer „<“ und „>“ entfernt. Aus einem Output Satz „<start> ich esse <end>“ wird daher einfach [’start‘, ‚ich‘, ‚esse‘, ‚end‘]. Somit ist der „<start>“ und „<end>“ Token nicht mehr klar erkennbar! Ich habe sie daher im JS Code von Anfang ersetzt durch „startToken“ und „endToken“.

Zunächst tokenisieren wir wieder jeden einzelnen Satz aus dem Datensatz und erstellen anschließend ein Vokabelverzeichnis für jede der beiden Sprachen. Abschließend ersetzen wir alle Wörter durch die Indizes aus dem Vokabelverzeichnis:

const natural = require("natural");

function tokenize(data) {
  const tokenizer = new natural.WordTokenizer();

  enData = data.map((row) => tokenizer.tokenize(row.en));
  deData = data.map((row) => tokenizer.tokenize(row.de));

  const enVocabulary = new Map();
  const deVocabulary = new Map();

  // Insert <pad> at index 0
  enVocabulary.set("<pad>", 0);
  deVocabulary.set("<pad>", 0);

  const fillVocabulary = (langData, vocabMap) => {
    langData.forEach((sentence) => {
      sentence.forEach((word) => {
        if (!vocabMap.has(word)) {
          const newIndex = vocabMap.size;
          vocabMap.set(word, newIndex);
        }
      });
    });
  };

  fillVocabulary(enData, enVocabulary);
  fillVocabulary(deData, deVocabulary);

  // Replace words with indexes
  const indexedEnData = enData.map((element) =>
    element.map((word) => enVocabulary.get(word))
  );
  const indexedDeData = deData.map((element) =>
    element.map((word) => deVocabulary.get(word))
  );

  return { en: indexedEnData, de: indexedDeData };
}

Um später die Resultate unseres Modells wieder in Wörter umwandeln zu können und um auch später im realen Anwendungsfall das Modell nutzen zu können, speichern wir die beiden Vokabelverzeichnisse ab. Ich habe dabei die Key und Value Paare getauscht, aber letztlich ist das nicht zwingend erforderlich:

const fs = require("fs");

// store the input and output key value pairs
  fs.writeFileSync(
    "vocabulary/inputVocableSet.json",
    JSON.stringify(switchKeysAndValues(Object.fromEntries(enVocabulary)))
  );
  fs.writeFileSync(
    "vocabulary/outputVocableSet.json",
    JSON.stringify(switchKeysAndValues(Object.fromEntries(deVocabulary)))
  );

function switchKeysAndValues(obj) {
  const switchedObj = {};
  for (const key in obj) {
    if (obj.hasOwnProperty(key)) {
      const value = obj[key];
      switchedObj[value] = key;
    }
  }
  return switchedObj;
}

Als Resultat erhalten wir ein JSON Objekt mit unseren Vokabeln:

Anschließend returnen wir das Ergebnis unserer Funktion:

Dateien zum Herunterladen

• NLP Tensorflow.js code (model has an error!)

The post NLP Anwendung: Tensorflow.js vs Tensorflow Python – Teil 1 appeared first on Nerd Corner.

Auch sollte der Fokus stehts auf clean Code legen und dieser ordentlich dokumentiert sein, besonders wenn ein Projekt größer wird zahlt sich ordentlich dokumentierte Arbeit aus. Um beispielsweise REST Endpunkte zu dokumentieren empfiehlt es sich Swagger zu benutzen. Die Swagger API Dokumentation bietet eine Übersicht über alle Endpunkte und sogar die Möglichkeit mit diesen zu interagieren.

Das könnte Sie auch interessieren: Angular Form SVG mit clickbaren Elementen

Liste der Komponenten

• Entwicklungsumgebung (z.B. VS Code)
• Node.js

Dokumentation mit Swagger

Obwohl Swagger recht bekannt ist, konnte ich keine detaillierte Anleitung für die Implementation finden. Ich möchte daher 2 Wege zur Implementierung von Swagger in einen bestehenden Node Server erklären. Die erste Möglichkeit besteht darin direkt zu jedem Endpunkt Swagger Parameter hinzuzufügen. Das ist wohl die schnellere Variante, kann allerdings abhängig von der Anzahl der Endpunkte unübersichtlich werden. In der zweiten Variante wird eine „swagger.json“ Datei erstellt, die die  Parameter der Endpunkte zusammenfasst.

Um Swagger nutzen zu können wird folgende Bibliothek bzw. deren Typerweiterung genutzt:

npm install --save  swagger-ui-express
npm install --save-dev @types/swagger-ui-express

Swagger erstellt eine Dokumentation der Endpunkte:

Diese können geöffnet werden und man sieht einen beispielhaften Request und einen beispielhaften Response:

Über den Button „Try it out“ kann direkt mit dem Endpunkt interagiert werden.

Swagger API Dokumentation mit Parametern

Diese Variante empfiehlt sich eher für kleinere Projekte. Zunächst müssen diese beiden Swagger Bibliotheken in das Projekt eingebunden werden:

npm install --save-dev @types/swagger-jsdoc 
npm install --save swagger-jsdoc

Die Bibliotheken werden in app.ts bzw. für nicht Typescript Nutzer app.js konfiguriert. Aufgrund der hier festgelegten Konfiguration befindet sich die Dokumentation unter „/api-docs“:

import express from "express";
import bodyParser from "body-parser";
import exampleRoutes from "./routes/example-route";
import swaggerJSDoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

const app = express();

const options = {
  definition: {
    openapi: "3.0.1",
    info: {
      title: "REST API for Swagger Documentation",
      version: "1.0.0",
    },
    schemes: ["http", "https"],
    servers: [{ url: "http://localhost:3000/" }],
  },
  apis: [
    `${__dirname}/routes/example-route.ts`,
    "./dist/routes/example-route.js",
  ],
};

const swaggerSpec = swaggerJSDoc(options);

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
app.use(bodyParser.json());
app.use(exampleRoutes);

app.listen(3000);

Der Endpunkt wird mit den Parametern folgendermaßen beschrieben:

import { Router } from "express";
import { exampleFunction } from "../controller/example";

const router = Router();

/**
 * @swagger
 * /example:
 *      post:
 *          summary: Send the text to the server
 *          tags:
 *              - ExampleEndpoints
 *          description: Send a message to the server and get a response added to the original text.
 *          requestBody:
 *              required: true
 *              content:
 *                  application/json:
 *                      schema:
 *                          type: object
 *                          properties:
 *                              responseText:
 *                                  type: string
 *                                  example: This is some example string! This is an endpoint
 *          responses:
 *              201:
 *                  description: Success
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: object
 *                              properties:
 *                                  text:
 *                                      type: string
 *                                      example: This is some example string!
 *              404:
 *                  description: Not found
 *              500:
 *                  description: Internal server error
 */
router.post("/example", exampleFunction);

export default router;

Swagger API Dokumentation mit swagger.json

Um eine bessere Übersicht zu haben und um die Dokumentation nicht mit dem eigentlichen Code zu vermischen empfiehlt sich die Nutzung einer, oder gar mehrerer json Dateien. Bei der Nutzung von TypeScript muss die Swagger.json Datei in die rootDirectory:

Auch hier wirdzunächst die Konfiguration in app.ts bzw. für nicht Typescript Nutzer in app.js festgelegt. Hier wird ebenfalls der Domainpfad „/api-docs“ für die Dokumentation gewählt:

import express from "express";
import bodyParser from "body-parser";
import exampleRoutes from "./routes/example-route";
import swaggerUi from "swagger-ui-express";

import * as swaggerDocument from "./swagger.json";

const app = express();

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.use(bodyParser.json());

app.use(exampleRoutes);

app.listen(3000);

Wichtiger Hinweis: Um JSON Dateien in ein Typescript Projekt zu importieren muss dies in der tsconfig.json erlaubt werden. Außerdem muss die JSON Datei sich in der root directory befinden:

{
  "compilerOptions": {
    "target": "es2016" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
    "module": "commonjs" /* Specify what module code is generated. */,
    "rootDir": "./src" /* Specify the root folder within your source files. */,
    "moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
    "resolveJsonModule": true /* Enable importing .json files. */,
    "outDir": "./dist" /* Specify an output folder for all emitted files. */,
    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
    "strict": true /* Enable all strict type-checking options. */,
    "skipLibCheck": true /* Skip type checking all .d.ts files. */
  }
}

Die vorherige Swagger Dokumentation mit Parametern würde somit in der swagger.json folgendermaßen aussehen:

{
  "openapi": "3.0.1",
  "info": {
    "title": "REST API for Swagger Documentation",
    "version": "1.0.0"
  },
  "schemes": ["http"],
  "servers": [{ "url": "http://localhost:3000/" }],
  "paths": {
    "/example": {
      "post": {
        "tags": ["ExampleEndpoints"],
        "summary": "Send a text to the server",
        "description": "Send a message to the server and get a response added to the original text.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExampleSchemaHeader"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleSchemaBody"
                }
              }
            }
          },
          "404": { "description": "Not found" },
          "500": { "description": "Internal server error" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ExampleSchemaBody": {
        "properties": {
          "responseText": {
            "type": "string",
            "example": "This is some example string! This is an endpoint"
          }
        }
      },
      "ExampleSchemaHeader": {
        "required": ["text"],
        "properties": {
          "text": {
            "type": "string",
            "example": "This is some example string!"
          }
        }
      }
    }
  }
}

Dateien zum Herunterladen

• Github Beispielprojekt für swagger Parameter
• Github Beispielprojekt für swagger.json

The post Swagger Api Doku zu Node Server hinzufügen appeared first on Nerd Corner.