You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opennlp.apache.org by ma...@apache.org on 2023/07/26 11:27:47 UTC

[opennlp] 01/01: improves existing JavaDoc of opennlp.dl component/package

This is an automated email from the ASF dual-hosted git repository.

mawiesne pushed a commit to branch OPENNLP-1506_Enhance_JavaDoc_in_opennlp.dl_package
in repository https://gitbox.apache.org/repos/asf/opennlp.git

commit dda901d75589fd99a12a8019eca2e4d1c27169a5
Author: Martin Wiesner <ma...@hs-heilbronn.de>
AuthorDate: Wed Jul 26 13:27:38 2023 +0200

    improves existing JavaDoc of opennlp.dl component/package
---
 .../src/main/java/opennlp/dl/AbstractDL.java       | 13 ++++-----
 .../opennlp/dl/doccat/DocumentCategorizerDL.java   | 20 +++++++++-----
 .../AverageClassificationScoringStrategy.java      |  6 +++--
 .../java/opennlp/dl/namefinder/NameFinderDL.java   | 31 ++++++++++++++++++++--
 .../java/opennlp/dl/vectors/SentenceVectorsDL.java | 14 +++++-----
 5 files changed, 59 insertions(+), 25 deletions(-)

diff --git a/opennlp-dl/src/main/java/opennlp/dl/AbstractDL.java b/opennlp-dl/src/main/java/opennlp/dl/AbstractDL.java
index 2d22a359..7d891bea 100644
--- a/opennlp-dl/src/main/java/opennlp/dl/AbstractDL.java
+++ b/opennlp-dl/src/main/java/opennlp/dl/AbstractDL.java
@@ -46,27 +46,24 @@ public abstract class AbstractDL {
   protected Map<String, Integer> vocab;
 
   /**
-   * Loads a vocabulary file from disk.
+   * Loads a vocabulary {@link File} from disk.
+   *
    * @param vocabFile The vocabulary file.
    * @return A map of vocabulary words to integer IDs.
-   * @throws IOException Thrown if the vocabulary file cannot be opened and read.
+   *
+   * @throws IOException Thrown if the vocabulary file cannot be opened or read.
    */
   public Map<String, Integer> loadVocab(final File vocabFile) throws IOException {
 
     final Map<String, Integer> vocab = new HashMap<>();
-
     final AtomicInteger counter = new AtomicInteger(0);
 
     try (Stream<String> lines = Files.lines(Path.of(vocabFile.getPath()))) {
 
-      lines.forEach(line -> {
-        vocab.put(line, counter.getAndIncrement());
-      });
-
+      lines.forEach(line -> vocab.put(line, counter.getAndIncrement()));
     }
 
     return vocab;
-
   }
 
 }
diff --git a/opennlp-dl/src/main/java/opennlp/dl/doccat/DocumentCategorizerDL.java b/opennlp-dl/src/main/java/opennlp/dl/doccat/DocumentCategorizerDL.java
index 28733c88..b4f5caa5 100644
--- a/opennlp-dl/src/main/java/opennlp/dl/doccat/DocumentCategorizerDL.java
+++ b/opennlp-dl/src/main/java/opennlp/dl/doccat/DocumentCategorizerDL.java
@@ -48,6 +48,10 @@ import opennlp.tools.tokenize.WordpieceTokenizer;
 /**
  * An implementation of {@link DocumentCategorizer} that performs document classification
  * using ONNX models.
+ *
+ * @see DocumentCategorizer
+ * @see InferenceOptions
+ * @see ClassificationScoringStrategy
  */
 public class DocumentCategorizerDL extends AbstractDL implements DocumentCategorizer {
 
@@ -58,16 +62,20 @@ public class DocumentCategorizerDL extends AbstractDL implements DocumentCategor
   private final InferenceOptions inferenceOptions;
 
   /**
-   * Creates a new document categorizer using ONNX models.
-   * @param modelFile The ONNX modelFile file.
-   * @param vocabFile The modelFile's vocabulary file.
+   * Instantiates a {@link DocumentCategorizer document categorizer} using ONNX models.
+   *
+   * @param model The ONNX model file.
+   * @param vocabulary The model file's vocabulary file.
    * @param categories The categories.
    * @param classificationScoringStrategy Implementation of {@link ClassificationScoringStrategy} used
    *                                      to calculate the classification scores given the score of each
    *                                      individual document part.
    * @param inferenceOptions {@link InferenceOptions} to control the inference.
+   *
+   * @throws OrtException Thrown if the {@code model} cannot be loaded.
+   * @throws IOException Thrown if errors occurred loading the {@code model} or {@code vocabulary}.
    */
-  public DocumentCategorizerDL(File modelFile, File vocabFile, Map<Integer, String> categories,
+  public DocumentCategorizerDL(File model, File vocabulary, Map<Integer, String> categories,
                                ClassificationScoringStrategy classificationScoringStrategy,
                                InferenceOptions inferenceOptions)
       throws IOException, OrtException {
@@ -79,8 +87,8 @@ public class DocumentCategorizerDL extends AbstractDL implements DocumentCategor
       sessionOptions.addCUDA(inferenceOptions.getGpuDeviceId());
     }
 
-    this.session = env.createSession(modelFile.getPath(), sessionOptions);
-    this.vocab = loadVocab(vocabFile);
+    this.session = env.createSession(model.getPath(), sessionOptions);
+    this.vocab = loadVocab(vocabulary);
     this.tokenizer = new WordpieceTokenizer(vocab.keySet());
     this.categories = categories;
     this.classificationScoringStrategy = classificationScoringStrategy;
diff --git a/opennlp-dl/src/main/java/opennlp/dl/doccat/scoring/AverageClassificationScoringStrategy.java b/opennlp-dl/src/main/java/opennlp/dl/doccat/scoring/AverageClassificationScoringStrategy.java
index b9b2f620..50c5825f 100644
--- a/opennlp-dl/src/main/java/opennlp/dl/doccat/scoring/AverageClassificationScoringStrategy.java
+++ b/opennlp-dl/src/main/java/opennlp/dl/doccat/scoring/AverageClassificationScoringStrategy.java
@@ -20,8 +20,10 @@ package opennlp.dl.doccat.scoring;
 import java.util.List;
 
 /**
- * Calculates the document classification scores by averaging the scores for
- * all individual parts of a document.
+ * A {@link ClassificationScoringStrategy} which calculates the document classification scores
+ * by averaging the scores for all individual parts of a document.
+ *
+ * @see ClassificationScoringStrategy
  */
 public class AverageClassificationScoringStrategy implements ClassificationScoringStrategy {
 
diff --git a/opennlp-dl/src/main/java/opennlp/dl/namefinder/NameFinderDL.java b/opennlp-dl/src/main/java/opennlp/dl/namefinder/NameFinderDL.java
index 803ece32..3cbf0e2a 100644
--- a/opennlp-dl/src/main/java/opennlp/dl/namefinder/NameFinderDL.java
+++ b/opennlp-dl/src/main/java/opennlp/dl/namefinder/NameFinderDL.java
@@ -18,6 +18,7 @@
 package opennlp.dl.namefinder;
 
 import java.io.File;
+import java.io.IOException;
 import java.nio.LongBuffer;
 import java.util.Arrays;
 import java.util.HashMap;
@@ -43,6 +44,9 @@ import opennlp.tools.util.Span;
 
 /**
  * An implementation of {@link TokenNameFinder} that uses ONNX models.
+ *
+ * @see TokenNameFinder
+ * @see InferenceOptions
  */
 public class NameFinderDL extends AbstractDL implements TokenNameFinder {
 
@@ -56,16 +60,39 @@ public class NameFinderDL extends AbstractDL implements TokenNameFinder {
   private final Map<Integer, String> ids2Labels;
   private final InferenceOptions inferenceOptions;
 
+  /**
+   * Instantiates a {@link TokenNameFinder name finder} using ONNX models.
+   * 
+   * @param model The ONNX model file.
+   * @param vocabulary The model file's vocabulary file.
+   * @param ids2Labels The mapping of ids to labels.
+   * @param sentenceDetector The {@link SentenceDetector} to be used.
+   *
+   * @throws OrtException Thrown if the {@code model} cannot be loaded.
+   * @throws IOException Thrown if errors occurred loading the {@code model} or {@code vocabulary}.
+   */
   public NameFinderDL(File model, File vocabulary, Map<Integer, String> ids2Labels,
-                      SentenceDetector sentenceDetector) throws Exception {
+                      SentenceDetector sentenceDetector) throws IOException, OrtException {
 
     this(model, vocabulary, ids2Labels, new InferenceOptions(), sentenceDetector);
 
   }
 
+  /**
+   * Instantiates a {@link TokenNameFinder name finder} using ONNX models.
+   *
+   * @param model The ONNX model file.
+   * @param vocabulary The model file's vocabulary file.
+   * @param ids2Labels The mapping of ids to labels.
+   * @param inferenceOptions {@link InferenceOptions} to control the inference.
+   * @param sentenceDetector The {@link SentenceDetector} to be used.
+   *
+   * @throws OrtException Thrown if the {@code model} cannot be loaded.
+   * @throws IOException Thrown if errors occurred loading the {@code model} or {@code vocabulary}.
+   */
   public NameFinderDL(File model, File vocabulary, Map<Integer, String> ids2Labels,
                       InferenceOptions inferenceOptions,
-                      SentenceDetector sentenceDetector) throws Exception {
+                      SentenceDetector sentenceDetector) throws IOException, OrtException {
 
     this.env = OrtEnvironment.getEnvironment();
 
diff --git a/opennlp-dl/src/main/java/opennlp/dl/vectors/SentenceVectorsDL.java b/opennlp-dl/src/main/java/opennlp/dl/vectors/SentenceVectorsDL.java
index b50cbe98..805b4118 100644
--- a/opennlp-dl/src/main/java/opennlp/dl/vectors/SentenceVectorsDL.java
+++ b/opennlp-dl/src/main/java/opennlp/dl/vectors/SentenceVectorsDL.java
@@ -28,8 +28,6 @@ import ai.onnxruntime.OnnxTensor;
 import ai.onnxruntime.OrtEnvironment;
 import ai.onnxruntime.OrtException;
 import ai.onnxruntime.OrtSession;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 import opennlp.dl.AbstractDL;
 import opennlp.dl.Tokens;
@@ -42,14 +40,14 @@ import opennlp.tools.tokenize.WordpieceTokenizer;
  */
 public class SentenceVectorsDL extends AbstractDL {
 
-  private static final Logger logger = LoggerFactory.getLogger(SentenceVectorsDL.class);
-
   /**
-   * Creates an instance of the class.
+   * Instantiates a {@link SentenceVectorsDL sentence detector} using ONNX models.
+   *
    * @param model The file name of a sentence vectors ONNX model.
    * @param vocabulary The file name of the vocabulary file for the model.
-   * @throws OrtException Thrown if the model cannot be loaded.
-   * @throws IOException Thrown if the vocabulary file cannot be loaded.
+   *
+   * @throws OrtException Thrown if the {@code model} cannot be loaded.
+   * @throws IOException Thrown if errors occurred loading the {@code model} or {@code vocabulary}.
    */
   public SentenceVectorsDL(final File model, final File vocabulary)
       throws OrtException, IOException {
@@ -63,7 +61,9 @@ public class SentenceVectorsDL extends AbstractDL {
 
   /**
    * Generates vectors given a sentence.
+   * 
    * @param sentence The input sentence.
+   *
    * @throws OrtException Thrown if an error occurs during inference.
    */
   public float[] getVectors(final String sentence) throws OrtException {