diff --git a/de/15.9/config/crawler-ocr.rst b/de/15.9/config/crawler-ocr.rst new file mode 100644 index 00000000..68c920c1 --- /dev/null +++ b/de/15.9/config/crawler-ocr.rst @@ -0,0 +1,202 @@ +================================== +OCR-Konfiguration +================================== + +Übersicht +========= + +|Fess| extrahiert Text aus Dokumenten mit Apache Tika. +Der Tesseract-OCR-Parser von Tika ist in |Fess| enthalten. Wenn Sie ihn aktivieren, erkennt |Fess| Text in Bildern und gescannten PDFs und macht ihn durchsuchbar. + +OCR wird ausgeführt, wenn beide der folgenden Bedingungen erfüllt sind: + +- Der Befehl ``tesseract`` ist auf dem Host installiert, auf dem der Crawler-Prozess von |Fess| läuft +- OCR ist in |Fess| aktiviert + +OCR ist standardmäßig deaktiviert. +Ist ``tesseract`` nicht installiert, überspringt |Fess| die OCR. Es tritt kein Fehler auf. + +Wofür OCR gilt +============== + +Bei aktivierter OCR gilt sie für Folgendes: + +- Bilddateien (PNG, JPEG, TIFF, GIF, BMP usw.) +- In Dokumente eingebettete Bilder, die Tika verarbeitet (z. B. Office-Dateien) +- PDFs mit leerer Textebene (gescannte PDFs) + +Behandlung gescannter PDFs +-------------------------- + +|Fess| extrahiert Text aus PDFs normalerweise mit PDFBox. +Ist OCR aktiviert und erhält PDFBox aus einem PDF überhaupt keinen Text, extrahiert |Fess| das PDF erneut über Tika. +Tika rendert die Seiten als Bilder und führt OCR darauf aus. + +.. note:: + PDFs, die bereits Text enthalten, werden nicht per OCR verarbeitet. + Gemischte PDFs, bei denen nur einige Seiten gescannte Bilder sind, werden nicht abgedeckt. + +Tesseract installieren +====================== + +Installieren Sie Tesseract auf dem Host, auf dem |Fess| läuft. +Um japanischen Text zu erkennen, benötigen Sie außerdem die japanischen Trainingsdaten (traineddata). + +Debian / Ubuntu:: + + $ sudo apt-get install tesseract-ocr tesseract-ocr-jpn + +RHEL / Rocky Linux / AlmaLinux (EPEL zuvor aktivieren):: + + $ sudo dnf install tesseract tesseract-langpack-jpn + +Die installierten Sprachen prüfen Sie mit folgendem Befehl:: + + $ tesseract --list-langs + +OCR aktivieren +============== + +Legen Sie in ``fess_config.properties`` die folgenden Eigenschaften fest. + +- ZIP-Paket: ``app/WEB-INF/classes/fess_config.properties`` +- RPM/DEB-Paket: ``/etc/fess/fess_config.properties`` + +:: + + # OCR aktivieren (Standard: false) + crawler.document.ocr.enabled=true + + # Tesseract-Sprache(n), mit + verbunden (Standard: eng) + crawler.document.ocr.language=jpn+eng + + # Timeout in Sekunden für einen Tesseract-Lauf (Standard: 120) + crawler.document.ocr.timeout=120 + +.. list-table:: + :header-rows: 1 + :widths: 35 15 50 + + * - Eigenschaft + - Standard + - Beschreibung + * - ``crawler.document.ocr.enabled`` + - ``false`` + - Mit ``true`` wird OCR aktiviert. + * - ``crawler.document.ocr.language`` + - ``eng`` + - Tesseract-Sprache(n). Mehrere Sprachen werden mit ``+`` verbunden (z. B. ``jpn+eng``). Die passenden Trainingsdaten (traineddata) müssen installiert sein. + * - ``crawler.document.ocr.timeout`` + - ``120`` + - Timeout für einen Tesseract-Lauf (ein Bild oder eine PDF-Seite) in Sekunden. + +Sie können diese Einstellungen auch als JVM-Systemeigenschaften angeben. +Geben Sie sie zum Beispiel in ``FESS_JAVA_OPTS`` an. Das ist in Docker-Umgebungen praktisch. + +:: + + -Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng + +.. note:: + Starten Sie |Fess| nach einer Änderung dieser Einstellungen neu. + +OCR mit Docker verwenden +======================== + +Um OCR in einer Docker-Umgebung zu nutzen, fügen Sie dem |Fess|-Image Tesseract hinzu. +Erstellen Sie mit ``compose/tesseract/Dockerfile`` aus `docker-fess `__ ein Image mit Tesseract. + +Beispiel für ``compose/tesseract/Dockerfile``:: + + FROM ghcr.io/codelibs/fess:15.9.0 + + RUN apk add --no-cache tesseract-ocr tesseract-ocr-data-osd tesseract-ocr-data-eng tesseract-ocr-data-jpn + +Ersetzen Sie in ``compose/compose.yaml`` die Zeile ``image:`` durch ``build: ./tesseract`` und aktivieren Sie die Zeile ``FESS_JAVA_OPTS``. +Das funktioniert genauso wie ``build: ./playwright``. + +:: + + services: + fess01: + # image: ghcr.io/codelibs/fess:15.9.0 + build: ./tesseract + container_name: fess01 + environment: + - "SEARCH_ENGINE_HTTP_URL=http://search01:9200" + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng" + +Erstellen Sie nach der Änderung das Image neu und starten Sie die Container:: + + $ docker compose up -d --build + +.. note:: + Wenn Sie ein Basis-Image verwenden, das nicht auf Alpine basiert (z. B. ``-noble`` oder ``-al2023``), installieren Sie Tesseract statt mit ``apk`` mit dem Paketmanager der jeweiligen Distribution. + +Weitere Informationen finden Sie unter :doc:`../install/install-docker`. + +Einstellungen pro Crawl-Konfiguration +===================================== + +Wenn Sie in den „Konfigurationsparametern“ einer Crawl-Konfiguration ``config.tika.tesseract.config`` angeben, können Sie die OCR-Einstellungen nur für diese Crawl-Konfiguration überschreiben. + +:: + + config.tika.tesseract.config=tesseract.properties + +``tesseract.properties`` ist ein Klassenpfad-Ressourcenname, kein Dateisystempfad. +Legen Sie die Datei im Konfigurationsverzeichnis von |Fess| ab, das im Klassenpfad des Crawlers liegt. + +- ZIP-Paket: ``app/WEB-INF/classes/`` +- RPM/DEB-Paket: ``/etc/fess/`` + +In ``tesseract.properties`` schreiben Sie Eigenschaften der Tika-Klasse ``TesseractOCRConfig``. +Zuverlässig angewendet werden nur einfache Schlüssel wie ``language`` und ``timeoutSeconds``. + +:: + + language=jpn + timeoutSeconds=300 + +Für diese Crawl-Konfiguration hat dies Vorrang vor den oben beschriebenen globalen Einstellungen. + +Betriebshinweise +================ + +- OCR ist rechenintensiv und verlangsamt das Crawlen erheblich. Erwägen Sie, die Anzahl der Crawler-Threads zu verringern oder OCR nur für die Crawl-Konfigurationen zu aktivieren, die sie benötigen. +- Bei neuen Web-Crawl-Konfigurationen schließt das standardmäßige Ausschlussmuster Bild-URLs (jpg, png, gif usw.) aus. Um Bilder auf einer Website zu crawlen, entfernen Sie diese aus „Vom Crawlen ausgeschlossene URL“. Beim Dateisystem-Crawl werden Bilder berücksichtigt. +- Auch die Größenbeschränkungen des Crawlers gelten. Die Größenbeschränkung für die Indexierung je Dateityp (Standard: 10 MB) finden Sie unter :doc:`crawler-basic`. +- Die OCR-Genauigkeit hängt von der Qualität des Scans ab. Handschrift wird im Allgemeinen nicht gut erkannt. + +Hinweise zum Upgrade +==================== + +Bis 15.8 schloss die mitgelieferte ``tika.xml`` ``org.apache.tika.parser.ocr.TesseractOCRParser`` aus. +Ab 15.9 schließt die mitgelieferte ``tika.xml`` diesen Parser nicht mehr aus. + +Wenn Sie eine angepasste ``tika.xml`` weiterverwenden, entfernen Sie die folgende Zeile: + +:: + + + +Bleibt diese Zeile bestehen, bleibt OCR auch mit ``crawler.document.ocr.enabled=true`` ausgeschaltet. + +Der Speicherort von ``tika.xml`` ist wie folgt: + +- ZIP-Paket: ``app/WEB-INF/conf/tika.xml`` +- RPM/DEB-Paket: ``/etc/fess/tika.xml`` + +OCR überprüfen +============== + +1. Legen Sie eine Dateisystem-Crawl-Konfiguration für einen Ordner an, der ein gescanntes Bild (ein Bild mit Text) enthält. +2. Führen Sie den Crawl aus. +3. Suchen Sie nach einem Wort, das im Bild vorkommt, und prüfen Sie, ob das Bild in den Suchergebnissen erscheint. + +Erscheint das Bild nicht, prüfen Sie Folgendes: + +- ``tesseract --list-langs`` listet die verwendete Sprache auf +- ``crawler.document.ocr.enabled`` ist ``true`` +- ``tika.xml`` schließt ``TesseractOCRParser`` nicht mehr aus +- ``fess-crawler.log`` des Crawls zeigt ``OCR is enabled`` (die Warnung ``Tesseract OCR is not available`` bedeutet, dass |Fess| Tesseract nicht verwenden kann) diff --git a/de/15.9/config/index.rst b/de/15.9/config/index.rst index e878beab..b72ef7c4 100644 --- a/de/15.9/config/index.rst +++ b/de/15.9/config/index.rst @@ -25,6 +25,7 @@ Ein umfassender Leitfaden zur Konfiguration von |Fess|. Jeder Abschnitt ist nach crawler-basic crawler-advanced crawler-thumbnail + crawler-ocr .. toctree:: :maxdepth: 2 diff --git a/en/15.9/config/crawler-ocr.rst b/en/15.9/config/crawler-ocr.rst new file mode 100644 index 00000000..e78a5c4a --- /dev/null +++ b/en/15.9/config/crawler-ocr.rst @@ -0,0 +1,202 @@ +================================== +OCR Configuration +================================== + +Overview +======== + +|Fess| extracts text from documents with Apache Tika. +Tika's Tesseract OCR parser is bundled with |Fess|. When you enable it, |Fess| recognizes text in images and scanned PDFs and makes that text searchable. + +OCR runs when both of the following conditions are met: + +- The ``tesseract`` command is installed on the host where the |Fess| crawler process runs +- OCR is enabled in |Fess| + +OCR is disabled by default. +If ``tesseract`` is not installed, |Fess| skips OCR. No error occurs. + +What OCR Applies To +=================== + +When OCR is enabled, it applies to the following: + +- Image files (PNG, JPEG, TIFF, GIF, BMP, etc.) +- Images embedded in documents handled by Tika (such as Office files) +- PDFs whose text layer is empty (scanned PDFs) + +Handling of Scanned PDFs +------------------------ + +|Fess| normally extracts text from PDFs with PDFBox. +When OCR is enabled and PDFBox gets no text at all from a PDF, |Fess| re-extracts the PDF through Tika. +Tika renders the pages as images and runs OCR on them. + +.. note:: + PDFs that already contain some text are not OCR'd. + Mixed PDFs, where only some pages are scanned images, are not covered. + +Installing Tesseract +==================== + +Install Tesseract on the host where |Fess| runs. +To recognize Japanese text, you also need the Japanese trained data (traineddata). + +Debian / Ubuntu:: + + $ sudo apt-get install tesseract-ocr tesseract-ocr-jpn + +RHEL / Rocky Linux / AlmaLinux (enable EPEL first):: + + $ sudo dnf install tesseract tesseract-langpack-jpn + +To check the installed languages, run:: + + $ tesseract --list-langs + +Enabling OCR +============ + +Set the following properties in ``fess_config.properties``. + +- ZIP package: ``app/WEB-INF/classes/fess_config.properties`` +- RPM/DEB package: ``/etc/fess/fess_config.properties`` + +:: + + # Enable OCR (default: false) + crawler.document.ocr.enabled=true + + # Tesseract language(s), joined with + (default: eng) + crawler.document.ocr.language=jpn+eng + + # Timeout in seconds for one Tesseract run (default: 120) + crawler.document.ocr.timeout=120 + +.. list-table:: + :header-rows: 1 + :widths: 35 15 50 + + * - Property + - Default + - Description + * - ``crawler.document.ocr.enabled`` + - ``false`` + - Set to ``true`` to enable OCR. + * - ``crawler.document.ocr.language`` + - ``eng`` + - Tesseract language(s). Join multiple languages with ``+`` (for example, ``jpn+eng``). The matching traineddata must be installed. + * - ``crawler.document.ocr.timeout`` + - ``120`` + - Timeout for one Tesseract run (one image or one PDF page), in seconds. + +You can also set these as JVM system properties. +For example, specify them in ``FESS_JAVA_OPTS``. This is handy in Docker environments. + +:: + + -Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng + +.. note:: + Restart |Fess| after changing these settings. + +Using OCR with Docker +===================== + +To use OCR in a Docker environment, add Tesseract to the |Fess| image. +Build an image with Tesseract by using ``compose/tesseract/Dockerfile`` in `docker-fess `__. + +Example ``compose/tesseract/Dockerfile``:: + + FROM ghcr.io/codelibs/fess:15.9.0 + + RUN apk add --no-cache tesseract-ocr tesseract-ocr-data-osd tesseract-ocr-data-eng tesseract-ocr-data-jpn + +In ``compose/compose.yaml``, replace the ``image:`` line with ``build: ./tesseract`` and enable the ``FESS_JAVA_OPTS`` line. +This works the same way as ``build: ./playwright``. + +:: + + services: + fess01: + # image: ghcr.io/codelibs/fess:15.9.0 + build: ./tesseract + container_name: fess01 + environment: + - "SEARCH_ENGINE_HTTP_URL=http://search01:9200" + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng" + +After the change, rebuild the image and start the containers:: + + $ docker compose up -d --build + +.. note:: + If you use a non-Alpine base image, such as ``-noble`` or ``-al2023``, add Tesseract with that distribution's package manager instead of ``apk``. + +See :doc:`../install/install-docker` for details. + +Per-Crawl-Configuration Settings +================================ + +If you specify ``config.tika.tesseract.config`` in the "Configuration Parameters" of a crawl configuration, you can override the OCR settings for that crawl configuration only. + +:: + + config.tika.tesseract.config=tesseract.properties + +``tesseract.properties`` is a classpath resource name, not a file system path. +Place the file in the |Fess| configuration directory, which is on the crawler's classpath. + +- ZIP package: ``app/WEB-INF/classes/`` +- RPM/DEB package: ``/etc/fess/`` + +In ``tesseract.properties``, write Tika ``TesseractOCRConfig`` properties. +Only simple keys such as ``language`` and ``timeoutSeconds`` are reliably applied. + +:: + + language=jpn + timeoutSeconds=300 + +For that crawl configuration, this takes precedence over the global settings above. + +Operational Notes +================= + +- OCR is CPU-intensive and slows crawling considerably. Consider reducing the number of crawler threads, or enabling OCR only for the crawl configurations that need it. +- For new web crawl configurations, the default excluded URL pattern excludes image URLs (jpg, png, gif, etc.). To crawl images on a web site, remove these from "Excluded URLs for Crawling". File crawls include images. +- The crawler's size limits also apply. For the indexing size limit per file type (default: 10 MB), see :doc:`crawler-basic`. +- OCR accuracy depends on the quality of the scan. Handwriting is generally not recognized well. + +Upgrade Notes +============= + +Up to 15.8, the bundled ``tika.xml`` excluded ``org.apache.tika.parser.ocr.TesseractOCRParser``. +From 15.9, the bundled ``tika.xml`` no longer excludes this parser. + +If you kept a customized ``tika.xml``, remove the following line: + +:: + + + +If this line remains, OCR stays off even with ``crawler.document.ocr.enabled=true``. + +The location of ``tika.xml`` is as follows: + +- ZIP package: ``app/WEB-INF/conf/tika.xml`` +- RPM/DEB package: ``/etc/fess/tika.xml`` + +Verifying OCR +============= + +1. Create a file crawl configuration for a folder that contains a scanned image (an image with text in it). +2. Run the crawl. +3. Search for a word that appears in the image and confirm that the image appears in the search results. + +If the image does not appear, check the following: + +- ``tesseract --list-langs`` lists the language you use +- ``crawler.document.ocr.enabled`` is ``true`` +- ``tika.xml`` does not still exclude ``TesseractOCRParser`` +- ``fess-crawler.log`` of the crawl shows ``OCR is enabled`` (a ``Tesseract OCR is not available`` warning means that |Fess| cannot use Tesseract) diff --git a/en/15.9/config/index.rst b/en/15.9/config/index.rst index 9a256e55..acd0eeae 100644 --- a/en/15.9/config/index.rst +++ b/en/15.9/config/index.rst @@ -25,6 +25,7 @@ This is a comprehensive guide for configuring |Fess|. Each section is organized crawler-basic crawler-advanced crawler-thumbnail + crawler-ocr .. toctree:: :maxdepth: 2 diff --git a/es/15.9/config/crawler-ocr.rst b/es/15.9/config/crawler-ocr.rst new file mode 100644 index 00000000..28e673c6 --- /dev/null +++ b/es/15.9/config/crawler-ocr.rst @@ -0,0 +1,202 @@ +================================== +Configuración de OCR +================================== + +Descripción general +=================== + +|Fess| extrae texto de los documentos con Apache Tika. +El analizador OCR de Tesseract de Tika se incluye en |Fess|. Al activarlo, |Fess| reconoce el texto de las imágenes y de los PDF escaneados y lo hace buscable. + +El OCR se ejecuta cuando se cumplen las dos condiciones siguientes: + +- El comando ``tesseract`` está instalado en el host donde se ejecuta el proceso del rastreador de |Fess| +- El OCR está activado en |Fess| + +El OCR está desactivado de forma predeterminada. +Si ``tesseract`` no está instalado, |Fess| omite el OCR. No se produce ningún error. + +A qué se aplica el OCR +====================== + +Cuando el OCR está activado, se aplica a lo siguiente: + +- Archivos de imagen (PNG, JPEG, TIFF, GIF, BMP, etc.) +- Imágenes incrustadas en documentos que procesa Tika (por ejemplo, archivos de Office) +- PDF cuya capa de texto está vacía (PDF escaneados) + +Tratamiento de los PDF escaneados +--------------------------------- + +|Fess| normalmente extrae el texto de los PDF con PDFBox. +Cuando el OCR está activado y PDFBox no obtiene ningún texto de un PDF, |Fess| vuelve a extraer el PDF mediante Tika. +Tika convierte las páginas en imágenes y les aplica OCR. + +.. note:: + Los PDF que ya contienen algo de texto no se procesan con OCR. + Los PDF mixtos, en los que solo algunas páginas son imágenes escaneadas, no están cubiertos. + +Instalación de Tesseract +======================== + +Instale Tesseract en el host donde se ejecuta |Fess|. +Para reconocer texto en japonés, también necesita los datos de entrenamiento en japonés (traineddata). + +Debian / Ubuntu:: + + $ sudo apt-get install tesseract-ocr tesseract-ocr-jpn + +RHEL / Rocky Linux / AlmaLinux (active EPEL antes):: + + $ sudo dnf install tesseract tesseract-langpack-jpn + +Para comprobar los idiomas instalados, ejecute:: + + $ tesseract --list-langs + +Activación del OCR +================== + +Configure las siguientes propiedades en ``fess_config.properties``. + +- Paquete ZIP: ``app/WEB-INF/classes/fess_config.properties`` +- Paquete RPM/DEB: ``/etc/fess/fess_config.properties`` + +:: + + # Activar el OCR (predeterminado: false) + crawler.document.ocr.enabled=true + + # Idioma(s) de Tesseract, unidos con + (predeterminado: eng) + crawler.document.ocr.language=jpn+eng + + # Tiempo de espera en segundos para una ejecución de Tesseract (predeterminado: 120) + crawler.document.ocr.timeout=120 + +.. list-table:: + :header-rows: 1 + :widths: 35 15 50 + + * - Propiedad + - Predeterminado + - Descripción + * - ``crawler.document.ocr.enabled`` + - ``false`` + - Establézcala en ``true`` para activar el OCR. + * - ``crawler.document.ocr.language`` + - ``eng`` + - Idioma(s) de Tesseract. Los varios idiomas se unen con ``+`` (por ejemplo, ``jpn+eng``). Deben estar instalados los datos de entrenamiento (traineddata) correspondientes. + * - ``crawler.document.ocr.timeout`` + - ``120`` + - Tiempo de espera de una ejecución de Tesseract (una imagen o una página de PDF), en segundos. + +También puede establecerlas como propiedades del sistema de la JVM. +Por ejemplo, indíquelas en ``FESS_JAVA_OPTS``. Resulta práctico en entornos Docker. + +:: + + -Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng + +.. note:: + Reinicie |Fess| después de cambiar esta configuración. + +Uso del OCR con Docker +====================== + +Para usar el OCR en un entorno Docker, añada Tesseract a la imagen de |Fess|. +Construya una imagen con Tesseract usando ``compose/tesseract/Dockerfile`` de `docker-fess `__. + +Ejemplo de ``compose/tesseract/Dockerfile``:: + + FROM ghcr.io/codelibs/fess:15.9.0 + + RUN apk add --no-cache tesseract-ocr tesseract-ocr-data-osd tesseract-ocr-data-eng tesseract-ocr-data-jpn + +En ``compose/compose.yaml``, sustituya la línea ``image:`` por ``build: ./tesseract`` y active la línea ``FESS_JAVA_OPTS``. +Funciona igual que ``build: ./playwright``. + +:: + + services: + fess01: + # image: ghcr.io/codelibs/fess:15.9.0 + build: ./tesseract + container_name: fess01 + environment: + - "SEARCH_ENGINE_HTTP_URL=http://search01:9200" + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng" + +Después del cambio, reconstruya la imagen e inicie los contenedores:: + + $ docker compose up -d --build + +.. note:: + Si usa una imagen base que no es Alpine, como ``-noble`` o ``-al2023``, añada Tesseract con el gestor de paquetes de esa distribución en lugar de ``apk``. + +Consulte :doc:`../install/install-docker` para más detalles. + +Configuración por configuración de rastreo +========================================== + +Si especifica ``config.tika.tesseract.config`` en los "Parámetros de configuración" de una configuración de rastreo, puede sobrescribir los ajustes de OCR solo para esa configuración de rastreo. + +:: + + config.tika.tesseract.config=tesseract.properties + +``tesseract.properties`` es el nombre de un recurso del classpath, no una ruta del sistema de archivos. +Coloque el archivo en el directorio de configuración de |Fess|, que está en el classpath del rastreador. + +- Paquete ZIP: ``app/WEB-INF/classes/`` +- Paquete RPM/DEB: ``/etc/fess/`` + +En ``tesseract.properties``, escriba propiedades de ``TesseractOCRConfig`` de Tika. +Solo se aplican de forma fiable las claves simples, como ``language`` y ``timeoutSeconds``. + +:: + + language=jpn + timeoutSeconds=300 + +Para esa configuración de rastreo, esto tiene prioridad sobre los ajustes globales descritos arriba. + +Notas operativas +================ + +- El OCR consume mucha CPU y ralentiza considerablemente el rastreo. Considere reducir el número de hilos del rastreador o activar el OCR solo en las configuraciones de rastreo que lo necesiten. +- En las configuraciones de rastreo web nuevas, el patrón de URL excluidas predeterminado excluye las URL de imágenes (jpg, png, gif, etc.). Para rastrear imágenes de un sitio web, elimínelas de "URL excluidas del rastreo". El rastreo de archivos incluye las imágenes. +- También se aplican los límites de tamaño del rastreador. Para el límite de tamaño de indexación por tipo de archivo (predeterminado: 10 MB), consulte :doc:`crawler-basic`. +- La precisión del OCR depende de la calidad del escaneo. En general, la escritura a mano no se reconoce bien. + +Notas de actualización +====================== + +Hasta la versión 15.8, el ``tika.xml`` incluido excluía ``org.apache.tika.parser.ocr.TesseractOCRParser``. +Desde la versión 15.9, el ``tika.xml`` incluido ya no excluye este analizador. + +Si conservó un ``tika.xml`` personalizado, elimine la siguiente línea: + +:: + + + +Si esta línea permanece, el OCR sigue desactivado aunque establezca ``crawler.document.ocr.enabled=true``. + +La ubicación de ``tika.xml`` es la siguiente: + +- Paquete ZIP: ``app/WEB-INF/conf/tika.xml`` +- Paquete RPM/DEB: ``/etc/fess/tika.xml`` + +Verificación del OCR +==================== + +1. Cree una configuración de rastreo de archivos para una carpeta que contenga una imagen escaneada (una imagen con texto). +2. Ejecute el rastreo. +3. Busque una palabra que aparezca en la imagen y compruebe que la imagen aparece en los resultados de búsqueda. + +Si la imagen no aparece, compruebe lo siguiente: + +- ``tesseract --list-langs`` muestra el idioma que usa +- ``crawler.document.ocr.enabled`` es ``true`` +- ``tika.xml`` ya no excluye ``TesseractOCRParser`` +- El ``fess-crawler.log`` del rastreo muestra ``OCR is enabled`` (la advertencia ``Tesseract OCR is not available`` indica que |Fess| no puede usar Tesseract) diff --git a/es/15.9/config/index.rst b/es/15.9/config/index.rst index 07e9427d..e81c0b6a 100644 --- a/es/15.9/config/index.rst +++ b/es/15.9/config/index.rst @@ -25,6 +25,7 @@ Guía integral sobre la configuración de |Fess|. Cada sección está organizada crawler-basic crawler-advanced crawler-thumbnail + crawler-ocr .. toctree:: :maxdepth: 2 diff --git a/fr/15.9/config/crawler-ocr.rst b/fr/15.9/config/crawler-ocr.rst new file mode 100644 index 00000000..ea74f5a8 --- /dev/null +++ b/fr/15.9/config/crawler-ocr.rst @@ -0,0 +1,202 @@ +================================== +Configuration de l'OCR +================================== + +Aperçu +====== + +|Fess| extrait le texte des documents avec Apache Tika. +L'analyseur OCR Tesseract de Tika est fourni avec |Fess|. Une fois activé, |Fess| reconnaît le texte des images et des PDF numérisés et le rend consultable par la recherche. + +L'OCR s'exécute lorsque les deux conditions suivantes sont réunies : + +- La commande ``tesseract`` est installée sur l'hôte où s'exécute le processus du crawler de |Fess| +- L'OCR est activé dans |Fess| + +L'OCR est désactivé par défaut. +Si ``tesseract`` n'est pas installé, |Fess| ignore l'OCR. Aucune erreur ne se produit. + +Éléments concernés par l'OCR +============================ + +Lorsque l'OCR est activé, il s'applique aux éléments suivants : + +- Les fichiers image (PNG, JPEG, TIFF, GIF, BMP, etc.) +- Les images intégrées dans des documents traités par Tika (par exemple, les fichiers Office) +- Les PDF dont la couche de texte est vide (PDF numérisés) + +Traitement des PDF numérisés +---------------------------- + +|Fess| extrait normalement le texte des PDF avec PDFBox. +Lorsque l'OCR est activé et que PDFBox n'obtient aucun texte d'un PDF, |Fess| extrait de nouveau le PDF via Tika. +Tika convertit les pages en images et leur applique l'OCR. + +.. note:: + Les PDF qui contiennent déjà du texte ne sont pas traités par l'OCR. + Les PDF mixtes, dont seules certaines pages sont des images numérisées, ne sont pas couverts. + +Installation de Tesseract +========================= + +Installez Tesseract sur l'hôte où s'exécute |Fess|. +Pour reconnaître le texte japonais, vous avez aussi besoin des données d'entraînement japonaises (traineddata). + +Debian / Ubuntu :: + + $ sudo apt-get install tesseract-ocr tesseract-ocr-jpn + +RHEL / Rocky Linux / AlmaLinux (activez d'abord EPEL) :: + + $ sudo dnf install tesseract tesseract-langpack-jpn + +Pour vérifier les langues installées, exécutez :: + + $ tesseract --list-langs + +Activation de l'OCR +=================== + +Définissez les propriétés suivantes dans ``fess_config.properties``. + +- Paquet ZIP : ``app/WEB-INF/classes/fess_config.properties`` +- Paquet RPM/DEB : ``/etc/fess/fess_config.properties`` + +:: + + # Activer l'OCR (par défaut : false) + crawler.document.ocr.enabled=true + + # Langue(s) de Tesseract, reliées par + (par défaut : eng) + crawler.document.ocr.language=jpn+eng + + # Délai d'expiration en secondes pour une exécution de Tesseract (par défaut : 120) + crawler.document.ocr.timeout=120 + +.. list-table:: + :header-rows: 1 + :widths: 35 15 50 + + * - Propriété + - Par défaut + - Description + * - ``crawler.document.ocr.enabled`` + - ``false`` + - Définissez ``true`` pour activer l'OCR. + * - ``crawler.document.ocr.language`` + - ``eng`` + - Langue(s) de Tesseract. Reliez plusieurs langues avec ``+`` (par exemple, ``jpn+eng``). Les données d'entraînement (traineddata) correspondantes doivent être installées. + * - ``crawler.document.ocr.timeout`` + - ``120`` + - Délai d'expiration d'une exécution de Tesseract (une image ou une page de PDF), en secondes. + +Vous pouvez aussi définir ces propriétés comme propriétés système de la JVM. +Par exemple, indiquez-les dans ``FESS_JAVA_OPTS``. C'est pratique dans les environnements Docker. + +:: + + -Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng + +.. note:: + Redémarrez |Fess| après avoir modifié ces paramètres. + +Utiliser l'OCR avec Docker +========================== + +Pour utiliser l'OCR dans un environnement Docker, ajoutez Tesseract à l'image de |Fess|. +Construisez une image avec Tesseract à l'aide de ``compose/tesseract/Dockerfile`` de `docker-fess `__. + +Exemple de ``compose/tesseract/Dockerfile`` :: + + FROM ghcr.io/codelibs/fess:15.9.0 + + RUN apk add --no-cache tesseract-ocr tesseract-ocr-data-osd tesseract-ocr-data-eng tesseract-ocr-data-jpn + +Dans ``compose/compose.yaml``, remplacez la ligne ``image:`` par ``build: ./tesseract`` et activez la ligne ``FESS_JAVA_OPTS``. +Cela fonctionne comme ``build: ./playwright``. + +:: + + services: + fess01: + # image: ghcr.io/codelibs/fess:15.9.0 + build: ./tesseract + container_name: fess01 + environment: + - "SEARCH_ENGINE_HTTP_URL=http://search01:9200" + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng" + +Après la modification, reconstruisez l'image et démarrez les conteneurs :: + + $ docker compose up -d --build + +.. note:: + Si vous utilisez une image de base qui n'est pas Alpine, comme ``-noble`` ou ``-al2023``, ajoutez Tesseract avec le gestionnaire de paquets de cette distribution à la place de ``apk``. + +Consultez :doc:`../install/install-docker` pour plus de détails. + +Paramètres par configuration de crawl +===================================== + +Si vous indiquez ``config.tika.tesseract.config`` dans les « Paramètres de configuration » d'une configuration de crawl, vous pouvez remplacer les paramètres d'OCR pour cette seule configuration de crawl. + +:: + + config.tika.tesseract.config=tesseract.properties + +``tesseract.properties`` est un nom de ressource du classpath, et non un chemin du système de fichiers. +Placez le fichier dans le répertoire de configuration de |Fess|, qui se trouve dans le classpath du crawler. + +- Paquet ZIP : ``app/WEB-INF/classes/`` +- Paquet RPM/DEB : ``/etc/fess/`` + +Dans ``tesseract.properties``, écrivez des propriétés de ``TesseractOCRConfig`` de Tika. +Seules les clés simples, telles que ``language`` et ``timeoutSeconds``, sont appliquées de manière fiable. + +:: + + language=jpn + timeoutSeconds=300 + +Pour cette configuration de crawl, ces valeurs ont priorité sur les paramètres globaux décrits ci-dessus. + +Remarques d'exploitation +======================== + +- L'OCR sollicite fortement le processeur et ralentit considérablement le crawl. Envisagez de réduire le nombre de threads du crawler ou de n'activer l'OCR que pour les configurations de crawl qui en ont besoin. +- Pour les nouvelles configurations de crawl Web, le motif d'URL exclues par défaut exclut les URL d'images (jpg, png, gif, etc.). Pour explorer les images d'un site Web, supprimez-les de « URL exclues du crawl ». Le crawl de fichiers inclut les images. +- Les limites de taille du crawler s'appliquent également. Pour la limite de taille d'indexation par type de fichier (par défaut : 10 Mo), consultez :doc:`crawler-basic`. +- La précision de l'OCR dépend de la qualité de la numérisation. L'écriture manuscrite n'est en général pas bien reconnue. + +Remarques sur la mise à niveau +============================== + +Jusqu'à la version 15.8, le fichier ``tika.xml`` fourni excluait ``org.apache.tika.parser.ocr.TesseractOCRParser``. +Depuis la version 15.9, le fichier ``tika.xml`` fourni n'exclut plus cet analyseur. + +Si vous avez conservé un fichier ``tika.xml`` personnalisé, supprimez la ligne suivante : + +:: + + + +Si cette ligne reste en place, l'OCR reste désactivé même avec ``crawler.document.ocr.enabled=true``. + +L'emplacement de ``tika.xml`` est le suivant : + +- Paquet ZIP : ``app/WEB-INF/conf/tika.xml`` +- Paquet RPM/DEB : ``/etc/fess/tika.xml`` + +Vérification de l'OCR +===================== + +1. Créez une configuration de crawl de fichiers pour un dossier contenant une image numérisée (une image comportant du texte). +2. Lancez le crawl. +3. Recherchez un mot qui figure dans l'image et vérifiez que l'image apparaît dans les résultats de recherche. + +Si l'image n'apparaît pas, vérifiez les points suivants : + +- ``tesseract --list-langs`` affiche la langue utilisée +- ``crawler.document.ocr.enabled`` vaut ``true`` +- ``tika.xml`` n'exclut plus ``TesseractOCRParser`` +- Le ``fess-crawler.log`` du crawl affiche ``OCR is enabled`` (l'avertissement ``Tesseract OCR is not available`` signifie que |Fess| ne peut pas utiliser Tesseract) diff --git a/fr/15.9/config/index.rst b/fr/15.9/config/index.rst index 7bdb37d2..67d1b0b9 100644 --- a/fr/15.9/config/index.rst +++ b/fr/15.9/config/index.rst @@ -25,6 +25,7 @@ Ce guide complet couvre la configuration de |Fess|. Chaque section est organisé crawler-basic crawler-advanced crawler-thumbnail + crawler-ocr .. toctree:: :maxdepth: 2 diff --git a/ja/15.9/config/crawler-ocr.rst b/ja/15.9/config/crawler-ocr.rst new file mode 100644 index 00000000..07f26f5a --- /dev/null +++ b/ja/15.9/config/crawler-ocr.rst @@ -0,0 +1,202 @@ +================================== +OCR（画像内の文字認識）の設定 +================================== + +概要 +==== + +|Fess| は Apache Tika を使ってドキュメントからテキストを抽出します。 +Tika の Tesseract OCR パーサーは |Fess| に同梱されており、これを有効にすると、画像やスキャンした PDF に含まれる文字を認識して検索対象にできます。 + +OCR は次の 2 つの条件がそろったときに実行されます。 + +- |Fess| のクローラープロセスが動作するホストに ``tesseract`` コマンドがインストールされている +- |Fess| で OCR が有効になっている + +OCR はデフォルトでは無効です。 +``tesseract`` がインストールされていない場合、|Fess| は OCR をスキップします。エラーにはなりません。 + +OCR の対象 +========== + +OCR を有効にすると、次のものが対象になります。 + +- 画像ファイル（PNG、JPEG、TIFF、GIF、BMP など） +- Tika が処理するドキュメントに埋め込まれた画像（Office ファイルなど） +- テキストレイヤーが空の PDF（スキャンした PDF） + +スキャンした PDF の扱い +----------------------- + +|Fess| は通常、PDFBox で PDF からテキストを抽出します。 +OCR が有効で、PDFBox が PDF からまったくテキストを取得できなかった場合、|Fess| はその PDF を Tika で再抽出します。 +このとき Tika がページを画像に変換し、OCR を実行します。 + +.. note:: + すでにテキストを含む PDF は OCR の対象になりません。 + 一部のページだけがスキャン画像の PDF（混在した PDF）は対象外です。 + +Tesseract のインストール +======================== + +|Fess| を実行するホストに Tesseract をインストールします。 +日本語の文字を認識するには、日本語の学習データ（traineddata）も必要です。 + +Debian / Ubuntu:: + + $ sudo apt-get install tesseract-ocr tesseract-ocr-jpn + +RHEL / Rocky Linux / AlmaLinux（EPEL を有効にしてください）:: + + $ sudo dnf install tesseract tesseract-langpack-jpn + +インストールされている言語は、次のコマンドで確認できます:: + + $ tesseract --list-langs + +OCR の有効化 +============ + +``fess_config.properties`` に次のプロパティを設定します。 + +- ZIP 版: ``app/WEB-INF/classes/fess_config.properties`` +- RPM/DEB 版: ``/etc/fess/fess_config.properties`` + +:: + + # OCR を有効にする（デフォルト: false） + crawler.document.ocr.enabled=true + + # Tesseract の言語（複数の場合は + で連結、デフォルト: eng） + crawler.document.ocr.language=jpn+eng + + # Tesseract 1 回の実行のタイムアウト（秒、デフォルト: 120） + crawler.document.ocr.timeout=120 + +.. list-table:: + :header-rows: 1 + :widths: 35 15 50 + + * - プロパティ + - デフォルト + - 説明 + * - ``crawler.document.ocr.enabled`` + - ``false`` + - ``true`` にすると OCR を有効にします。 + * - ``crawler.document.ocr.language`` + - ``eng`` + - Tesseract の言語です。複数の言語は ``+`` で連結します（例: ``jpn+eng``）。対応する traineddata がインストールされている必要があります。 + * - ``crawler.document.ocr.timeout`` + - ``120`` + - Tesseract 1 回の実行（画像 1 枚、または PDF の 1 ページ）のタイムアウトです。単位は秒です。 + +これらの設定は、JVM のシステムプロパティとしても指定できます。 +たとえば ``FESS_JAVA_OPTS`` に次のように指定します。Docker 環境で便利です。 + +:: + + -Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng + +.. note:: + 設定を変更した後は、|Fess| を再起動してください。 + +Docker で使う場合 +================= + +Docker 環境で OCR を使うには、|Fess| のイメージに Tesseract を追加します。 +`docker-fess `__ の ``compose/tesseract/Dockerfile`` を使って、Tesseract を追加したイメージをビルドします。 + +``compose/tesseract/Dockerfile`` の例:: + + FROM ghcr.io/codelibs/fess:15.9.0 + + RUN apk add --no-cache tesseract-ocr tesseract-ocr-data-osd tesseract-ocr-data-eng tesseract-ocr-data-jpn + +``compose/compose.yaml`` では、``image:`` の行を ``build: ./tesseract`` に置き換え、``FESS_JAVA_OPTS`` の行を有効にします。 +``build: ./playwright`` と同じ使い方です。 + +:: + + services: + fess01: + # image: ghcr.io/codelibs/fess:15.9.0 + build: ./tesseract + container_name: fess01 + environment: + - "SEARCH_ENGINE_HTTP_URL=http://search01:9200" + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng" + +変更後は、イメージを再ビルドしてコンテナーを起動します:: + + $ docker compose up -d --build + +.. note:: + ``-noble`` や ``-al2023`` など、Alpine 以外のベースイメージを使う場合は、``apk`` の代わりにそのディストリビューションのパッケージマネージャーで Tesseract を追加してください。 + +詳細は :doc:`../install/install-docker` を参照してください。 + +クロール設定ごとの設定 +====================== + +クロール設定の「設定パラメーター」に ``config.tika.tesseract.config`` を指定すると、そのクロール設定に限って OCR の設定を上書きできます。 + +:: + + config.tika.tesseract.config=tesseract.properties + +``tesseract.properties`` はクラスパス上のリソース名です。ファイルシステムのパスではありません。 +ファイルは、クローラーのクラスパスに含まれる |Fess| の設定ディレクトリに置きます。 + +- ZIP 版: ``app/WEB-INF/classes/`` +- RPM/DEB 版: ``/etc/fess/`` + +``tesseract.properties`` には、Tika の ``TesseractOCRConfig`` のプロパティを記述します。 +確実に反映されるのは ``language`` や ``timeoutSeconds`` などの単純なキーです。 + +:: + + language=jpn + timeoutSeconds=300 + +この指定は、このクロール設定について、上記のグローバル設定より優先されます。 + +運用上の注意 +============ + +- OCR は CPU に高い負荷をかけ、クロールの処理時間が大幅に長くなります。クローラーのスレッド数を減らす、OCR が必要なクロール設定だけで有効にするなど、負荷を考慮してください。 +- Web クロール設定では、新規作成時のデフォルトで画像の URL（jpg、png、gif など）がクロール対象から除外されます。Web サイトの画像をクロールするには、「クロール対象から除外するURL」からこれらを削除してください。ファイルクロールでは、画像もクロール対象になります。 +- クローラーの取得サイズの上限も適用されます。ファイルの種類ごとのインデックスサイズの上限（デフォルトは 10MB）については :doc:`crawler-basic` を参照してください。 +- OCR の精度は、スキャンした画像の品質に左右されます。手書きの文字は、一般に認識されにくくなります。 + +アップグレード時の注意 +====================== + +15.8 以前の同梱の ``tika.xml`` は、``org.apache.tika.parser.ocr.TesseractOCRParser`` を除外していました。 +15.9 からは、同梱の ``tika.xml`` はこのパーサーを除外しません。 + +``tika.xml`` をカスタマイズして使い続けている場合は、次の行を削除してください。 + +:: + + + +この行が残っていると、``crawler.document.ocr.enabled=true`` を指定しても OCR は無効のままです。 + +``tika.xml`` の場所は次のとおりです。 + +- ZIP 版: ``app/WEB-INF/conf/tika.xml`` +- RPM/DEB 版: ``/etc/fess/tika.xml`` + +動作確認 +======== + +1. スキャンした画像（文字を含む画像）を置いたフォルダーを、ファイルクロールの対象にします。 +2. クロールを実行します。 +3. 画像に含まれる単語で検索し、その画像が検索結果に表示されることを確認します。 + +検索結果に表示されない場合は、次の点を確認してください。 + +- ``tesseract --list-langs`` で、使用する言語が表示される +- ``crawler.document.ocr.enabled`` が ``true`` になっている +- ``tika.xml`` に ``TesseractOCRParser`` の除外が残っていない +- クロール時の ``fess-crawler.log`` に ``OCR is enabled`` が出力されている（``Tesseract OCR is not available`` の警告が出る場合は、|Fess| から Tesseract を利用できていません） diff --git a/ja/15.9/config/index.rst b/ja/15.9/config/index.rst index 5c4a9143..1bb8394d 100644 --- a/ja/15.9/config/index.rst +++ b/ja/15.9/config/index.rst @@ -25,6 +25,7 @@ crawler-basic crawler-advanced crawler-thumbnail + crawler-ocr .. toctree:: :maxdepth: 2 diff --git a/ko/15.9/config/crawler-ocr.rst b/ko/15.9/config/crawler-ocr.rst new file mode 100644 index 00000000..e3b015a4 --- /dev/null +++ b/ko/15.9/config/crawler-ocr.rst @@ -0,0 +1,202 @@ +================================== +OCR(이미지 내 문자 인식) 설정 +================================== + +개요 +==== + +|Fess|\ 는 Apache Tika를 사용하여 문서에서 텍스트를 추출합니다. +Tika의 Tesseract OCR 파서는 |Fess|\ 에 포함되어 있으며, 이를 활성화하면 이미지나 스캔한 PDF에 포함된 문자를 인식하여 검색 대상으로 만들 수 있습니다. + +OCR은 다음 두 조건이 모두 충족될 때 실행됩니다. + +- |Fess| 크롤러 프로세스가 동작하는 호스트에 ``tesseract`` 명령이 설치되어 있음 +- |Fess|\ 에서 OCR이 활성화되어 있음 + +OCR은 기본적으로 비활성화되어 있습니다. +``tesseract``\ 가 설치되어 있지 않으면 |Fess|\ 는 OCR을 건너뜁니다. 오류는 발생하지 않습니다. + +OCR 대상 +======== + +OCR을 활성화하면 다음이 대상이 됩니다. + +- 이미지 파일(PNG, JPEG, TIFF, GIF, BMP 등) +- Tika가 처리하는 문서에 포함된 이미지(Office 파일 등) +- 텍스트 레이어가 비어 있는 PDF(스캔한 PDF) + +스캔한 PDF의 처리 +----------------- + +|Fess|\ 는 보통 PDFBox로 PDF에서 텍스트를 추출합니다. +OCR이 활성화되어 있고 PDFBox가 PDF에서 텍스트를 전혀 얻지 못한 경우, |Fess|\ 는 해당 PDF를 Tika로 다시 추출합니다. +이때 Tika가 페이지를 이미지로 변환하여 OCR을 실행합니다. + +.. note:: + 이미 텍스트를 포함하고 있는 PDF는 OCR 대상이 되지 않습니다. + 일부 페이지만 스캔 이미지인 PDF(혼합 PDF)는 대상 외입니다. + +Tesseract 설치 +============== + +|Fess|\ 를 실행하는 호스트에 Tesseract를 설치합니다. +일본어 문자를 인식하려면 일본어 학습 데이터(traineddata)도 필요합니다. + +Debian / Ubuntu:: + + $ sudo apt-get install tesseract-ocr tesseract-ocr-jpn + +RHEL / Rocky Linux / AlmaLinux (EPEL을 활성화하십시오):: + + $ sudo dnf install tesseract tesseract-langpack-jpn + +설치된 언어는 다음 명령으로 확인할 수 있습니다:: + + $ tesseract --list-langs + +OCR 활성화 +========== + +``fess_config.properties``\ 에 다음 프로퍼티를 설정합니다. + +- ZIP 버전: ``app/WEB-INF/classes/fess_config.properties`` +- RPM/DEB 버전: ``/etc/fess/fess_config.properties`` + +:: + + # OCR을 활성화(기본값: false) + crawler.document.ocr.enabled=true + + # Tesseract 언어(여러 개인 경우 +로 연결, 기본값: eng) + crawler.document.ocr.language=jpn+eng + + # Tesseract 1회 실행의 타임아웃(초, 기본값: 120) + crawler.document.ocr.timeout=120 + +.. list-table:: + :header-rows: 1 + :widths: 35 15 50 + + * - 프로퍼티 + - 기본값 + - 설명 + * - ``crawler.document.ocr.enabled`` + - ``false`` + - ``true``\ 로 설정하면 OCR이 활성화됩니다. + * - ``crawler.document.ocr.language`` + - ``eng`` + - Tesseract 언어입니다. 여러 언어는 ``+``\ 로 연결합니다(예: ``jpn+eng``). 해당 traineddata가 설치되어 있어야 합니다. + * - ``crawler.document.ocr.timeout`` + - ``120`` + - Tesseract 1회 실행(이미지 1장 또는 PDF 1페이지)의 타임아웃입니다. 단위는 초입니다. + +이 설정은 JVM 시스템 프로퍼티로도 지정할 수 있습니다. +예를 들어 ``FESS_JAVA_OPTS``\ 에 다음과 같이 지정합니다. Docker 환경에서 편리합니다. + +:: + + -Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng + +.. note:: + 설정을 변경한 후에는 |Fess|\ 를 재시작하십시오. + +Docker에서 사용하는 경우 +======================== + +Docker 환경에서 OCR을 사용하려면 |Fess| 이미지에 Tesseract를 추가합니다. +`docker-fess `__\ 의 ``compose/tesseract/Dockerfile``\ 을 사용하여 Tesseract를 추가한 이미지를 빌드합니다. + +``compose/tesseract/Dockerfile`` 예:: + + FROM ghcr.io/codelibs/fess:15.9.0 + + RUN apk add --no-cache tesseract-ocr tesseract-ocr-data-osd tesseract-ocr-data-eng tesseract-ocr-data-jpn + +``compose/compose.yaml``\ 에서 ``image:`` 행을 ``build: ./tesseract``\ 로 바꾸고 ``FESS_JAVA_OPTS`` 행을 활성화합니다. +``build: ./playwright``\ 와 같은 방식입니다. + +:: + + services: + fess01: + # image: ghcr.io/codelibs/fess:15.9.0 + build: ./tesseract + container_name: fess01 + environment: + - "SEARCH_ENGINE_HTTP_URL=http://search01:9200" + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng" + +변경 후에는 이미지를 다시 빌드하여 컨테이너를 시작합니다:: + + $ docker compose up -d --build + +.. note:: + ``-noble``\ 이나 ``-al2023`` 등 Alpine이 아닌 베이스 이미지를 사용하는 경우, ``apk`` 대신 해당 배포판의 패키지 관리자로 Tesseract를 추가하십시오. + +자세한 내용은 :doc:`../install/install-docker`\ 를 참조하십시오. + +크롤링 설정별 설정 +================== + +크롤링 설정의 「설정 파라미터」에 ``config.tika.tesseract.config``\ 를 지정하면, 해당 크롤링 설정에 한해 OCR 설정을 덮어쓸 수 있습니다. + +:: + + config.tika.tesseract.config=tesseract.properties + +``tesseract.properties``\ 는 클래스패스 상의 리소스 이름입니다. 파일 시스템 경로가 아닙니다. +파일은 크롤러의 클래스패스에 포함된 |Fess| 설정 디렉터리에 둡니다. + +- ZIP 버전: ``app/WEB-INF/classes/`` +- RPM/DEB 버전: ``/etc/fess/`` + +``tesseract.properties``\ 에는 Tika의 ``TesseractOCRConfig`` 프로퍼티를 작성합니다. +확실하게 반영되는 것은 ``language``\ 나 ``timeoutSeconds`` 같은 단순한 키입니다. + +:: + + language=jpn + timeoutSeconds=300 + +이 크롤링 설정에 대해서는 위의 전역 설정보다 이 지정이 우선합니다. + +운영상의 주의 +============= + +- OCR은 CPU에 높은 부하를 주며 크롤링 처리 시간이 크게 늘어납니다. 크롤러 스레드 수를 줄이거나 OCR이 필요한 크롤링 설정에서만 활성화하는 등 부하를 고려하십시오. +- 웹 크롤링 설정에서는 신규 생성 시 기본값으로 이미지 URL(jpg, png, gif 등)이 크롤링 대상에서 제외됩니다. 웹 사이트의 이미지를 크롤링하려면 「크롤링 대상에서 제외할 URL」에서 이를 삭제하십시오. 파일 크롤링에서는 이미지도 크롤링 대상이 됩니다. +- 크롤러의 크기 제한도 적용됩니다. 파일 종류별 인덱스 크기 상한(기본값 10MB)에 대해서는 :doc:`crawler-basic`\ 을 참조하십시오. +- OCR 정확도는 스캔한 이미지의 품질에 좌우됩니다. 손글씨는 일반적으로 인식되기 어렵습니다. + +업그레이드 시 주의 +================== + +15.8 이전에 포함된 ``tika.xml``\ 은 ``org.apache.tika.parser.ocr.TesseractOCRParser``\ 를 제외하고 있었습니다. +15.9부터는 포함된 ``tika.xml``\ 이 이 파서를 제외하지 않습니다. + +``tika.xml``\ 을 커스터마이즈하여 계속 사용하고 있는 경우, 다음 행을 삭제하십시오. + +:: + + + +이 행이 남아 있으면 ``crawler.document.ocr.enabled=true``\ 를 지정해도 OCR은 비활성화된 상태로 유지됩니다. + +``tika.xml``\ 의 위치는 다음과 같습니다. + +- ZIP 버전: ``app/WEB-INF/conf/tika.xml`` +- RPM/DEB 버전: ``/etc/fess/tika.xml`` + +동작 확인 +========= + +1. 스캔한 이미지(문자가 포함된 이미지)를 둔 폴더를 파일 크롤링 대상으로 설정합니다. +2. 크롤링을 실행합니다. +3. 이미지에 포함된 단어로 검색하여 해당 이미지가 검색 결과에 표시되는지 확인합니다. + +검색 결과에 표시되지 않으면 다음 사항을 확인하십시오. + +- ``tesseract --list-langs``\ 에 사용하는 언어가 표시됨 +- ``crawler.document.ocr.enabled``\ 가 ``true``\ 로 되어 있음 +- ``tika.xml``\ 에 ``TesseractOCRParser`` 제외가 남아 있지 않음 +- 크롤링 시 ``fess-crawler.log``\ 에 ``OCR is enabled``\ 가 출력됨(``Tesseract OCR is not available`` 경고가 출력되면 |Fess|\ 에서 Tesseract를 사용할 수 없는 상태입니다) diff --git a/ko/15.9/config/index.rst b/ko/15.9/config/index.rst index 11c339cb..9f306ce4 100644 --- a/ko/15.9/config/index.rst +++ b/ko/15.9/config/index.rst @@ -25,6 +25,7 @@ crawler-basic crawler-advanced crawler-thumbnail + crawler-ocr .. toctree:: :maxdepth: 2 diff --git a/zh-cn/15.9/config/crawler-ocr.rst b/zh-cn/15.9/config/crawler-ocr.rst new file mode 100644 index 00000000..0aa1a8bc --- /dev/null +++ b/zh-cn/15.9/config/crawler-ocr.rst @@ -0,0 +1,202 @@ +================================== +OCR（图像文字识别）配置 +================================== + +概述 +==== + +|Fess| 使用 Apache Tika 从文档中提取文本。 +Tika 的 Tesseract OCR 解析器已包含在 |Fess| 中。启用后，可以识别图像和扫描版 PDF 中的文字，并将其作为搜索对象。 + +满足以下两个条件时，将执行 OCR。 + +- 运行 |Fess| 爬虫进程的主机上已安装 ``tesseract`` 命令 +- |Fess| 中已启用 OCR + +OCR 默认处于禁用状态。 +如果未安装 ``tesseract``，|Fess| 会跳过 OCR，不会报错。 + +OCR 的对象 +========== + +启用 OCR 后，以下内容将成为对象。 + +- 图像文件（PNG、JPEG、TIFF、GIF、BMP 等） +- 由 Tika 处理的文档中嵌入的图像（Office 文件等） +- 文本层为空的 PDF（扫描版 PDF） + +扫描版 PDF 的处理 +----------------- + +|Fess| 通常使用 PDFBox 从 PDF 中提取文本。 +启用 OCR 且 PDFBox 完全无法从 PDF 中获取文本时，|Fess| 会通过 Tika 重新提取该 PDF。 +此时 Tika 会将页面转换为图像并执行 OCR。 + +.. note:: + 已包含文本的 PDF 不会成为 OCR 的对象。 + 只有部分页面是扫描图像的 PDF（混合 PDF）不在对象范围内。 + +安装 Tesseract +============== + +在运行 |Fess| 的主机上安装 Tesseract。 +要识别日文文字，还需要日文的训练数据（traineddata）。 + +Debian / Ubuntu:: + + $ sudo apt-get install tesseract-ocr tesseract-ocr-jpn + +RHEL / Rocky Linux / AlmaLinux（请先启用 EPEL）:: + + $ sudo dnf install tesseract tesseract-langpack-jpn + +可以通过以下命令确认已安装的语言:: + + $ tesseract --list-langs + +启用 OCR +======== + +在 ``fess_config.properties`` 中设置以下属性。 + +- ZIP 版: ``app/WEB-INF/classes/fess_config.properties`` +- RPM/DEB 版: ``/etc/fess/fess_config.properties`` + +:: + + # 启用 OCR（默认值: false） + crawler.document.ocr.enabled=true + + # Tesseract 的语言（多个语言用 + 连接，默认值: eng） + crawler.document.ocr.language=jpn+eng + + # Tesseract 单次运行的超时时间（秒，默认值: 120） + crawler.document.ocr.timeout=120 + +.. list-table:: + :header-rows: 1 + :widths: 35 15 50 + + * - 属性 + - 默认值 + - 说明 + * - ``crawler.document.ocr.enabled`` + - ``false`` + - 设置为 ``true`` 即启用 OCR。 + * - ``crawler.document.ocr.language`` + - ``eng`` + - Tesseract 的语言。多个语言用 ``+`` 连接（例如 ``jpn+eng``）。必须已安装对应的 traineddata。 + * - ``crawler.document.ocr.timeout`` + - ``120`` + - Tesseract 单次运行（一张图像或 PDF 的一页）的超时时间，单位为秒。 + +这些设置也可以作为 JVM 系统属性指定。 +例如在 ``FESS_JAVA_OPTS`` 中按如下方式指定。这在 Docker 环境中很方便。 + +:: + + -Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng + +.. note:: + 更改设置后，请重启 |Fess|。 + +在 Docker 中使用 +================ + +要在 Docker 环境中使用 OCR，请在 |Fess| 镜像中添加 Tesseract。 +使用 `docker-fess `__ 的 ``compose/tesseract/Dockerfile`` 构建添加了 Tesseract 的镜像。 + +``compose/tesseract/Dockerfile`` 示例:: + + FROM ghcr.io/codelibs/fess:15.9.0 + + RUN apk add --no-cache tesseract-ocr tesseract-ocr-data-osd tesseract-ocr-data-eng tesseract-ocr-data-jpn + +在 ``compose/compose.yaml`` 中，将 ``image:`` 行替换为 ``build: ./tesseract``，并启用 ``FESS_JAVA_OPTS`` 行。 +用法与 ``build: ./playwright`` 相同。 + +:: + + services: + fess01: + # image: ghcr.io/codelibs/fess:15.9.0 + build: ./tesseract + container_name: fess01 + environment: + - "SEARCH_ENGINE_HTTP_URL=http://search01:9200" + - "FESS_JAVA_OPTS=-Dfess.config.crawler.document.ocr.enabled=true -Dfess.config.crawler.document.ocr.language=jpn+eng" + +更改后，重新构建镜像并启动容器:: + + $ docker compose up -d --build + +.. note:: + 如果使用 ``-noble`` 或 ``-al2023`` 等非 Alpine 的基础镜像，请使用该发行版的包管理器代替 ``apk`` 来添加 Tesseract。 + +详情请参阅 :doc:`../install/install-docker`。 + +按爬取配置进行设置 +================== + +在爬取配置的“配置参数”中指定 ``config.tika.tesseract.config``，可以仅针对该爬取配置覆盖 OCR 设置。 + +:: + + config.tika.tesseract.config=tesseract.properties + +``tesseract.properties`` 是类路径上的资源名称，不是文件系统路径。 +请将文件放在 |Fess| 的配置目录中，该目录包含在爬虫的类路径中。 + +- ZIP 版: ``app/WEB-INF/classes/`` +- RPM/DEB 版: ``/etc/fess/`` + +在 ``tesseract.properties`` 中编写 Tika 的 ``TesseractOCRConfig`` 属性。 +能够可靠生效的只有 ``language`` 和 ``timeoutSeconds`` 等简单的键。 + +:: + + language=jpn + timeoutSeconds=300 + +对于该爬取配置，此设置优先于上述全局设置。 + +运维注意事项 +============ + +- OCR 会给 CPU 带来很高的负载，并使爬取的处理时间大幅增加。请考虑减少爬虫的线程数，或仅在需要 OCR 的爬取配置中启用等，以控制负载。 +- 在 Web 爬取配置中，新建时的默认设置会将图像 URL（jpg、png、gif 等）从爬取对象中排除。要爬取网站上的图像，请从“从爬取对象中排除的URL”中删除这些项。文件爬取会将图像也作为爬取对象。 +- 爬虫的大小限制同样适用。关于按文件类型设置的索引大小上限（默认值 10MB），请参阅 :doc:`crawler-basic`。 +- OCR 的精度取决于扫描图像的质量。手写文字通常难以被识别。 + +升级注意事项 +============ + +15.8 及更早版本中自带的 ``tika.xml`` 排除了 ``org.apache.tika.parser.ocr.TesseractOCRParser``。 +从 15.9 起，自带的 ``tika.xml`` 不再排除该解析器。 + +如果您一直在使用自定义的 ``tika.xml``，请删除以下行。 + +:: + + + +如果保留此行，即使指定了 ``crawler.document.ocr.enabled=true``，OCR 仍然保持禁用。 + +``tika.xml`` 的位置如下。 + +- ZIP 版: ``app/WEB-INF/conf/tika.xml`` +- RPM/DEB 版: ``/etc/fess/tika.xml`` + +确认运行 +======== + +1. 将放有扫描图像（包含文字的图像）的文件夹设为文件爬取的对象。 +2. 执行爬取。 +3. 使用图像中包含的单词进行搜索，确认该图像显示在搜索结果中。 + +如果搜索结果中没有显示，请确认以下几点。 + +- ``tesseract --list-langs`` 中显示所使用的语言 +- ``crawler.document.ocr.enabled`` 为 ``true`` +- ``tika.xml`` 中没有残留对 ``TesseractOCRParser`` 的排除 +- 爬取时的 ``fess-crawler.log`` 中输出了 ``OCR is enabled`` （如果输出 ``Tesseract OCR is not available`` 警告，则表示 |Fess| 无法使用 Tesseract） diff --git a/zh-cn/15.9/config/index.rst b/zh-cn/15.9/config/index.rst index 77e253af..2f5c7ce9 100644 --- a/zh-cn/15.9/config/index.rst +++ b/zh-cn/15.9/config/index.rst @@ -25,6 +25,7 @@ crawler-basic crawler-advanced crawler-thumbnail + crawler-ocr .. toctree:: :maxdepth: 2