docs: document the length chunker boundary settings

de/15.8/config/search-semantic.rst

@@ -146,10 +146,24 @@ Einstellungen in system.properties
      - Chunking-Methode
    * - ``content_chunker.length.chunk_size``
      - ``800``
-     - Anzahl der Zeichen pro Chunk
+     - Anzahl der Zeichen pro Chunk (Zielwert, siehe Hinweis unten)
    * - ``content_chunker.length.overlap``
      - ``0``
      - Anzahl der Zeichen, die sich zwischen Chunks überlappen
+   * - ``content_chunker.length.boundary.enabled``
+     - ``true``
+     - Verschiebt jeden Schnitt innerhalb des Suchfensters zur am besten geeigneten Grenze,
+       wobei ein Zeilenumbruch oder Satzende Vorrang vor einem Teilsatztrennzeichen oder
+       Leerzeichen hat und diese ihrerseits Vorrang vor einem Schriftsystemwechsel haben,
+       anstatt genau bei ``chunk_size`` Zeichen zu schneiden
+   * - ``content_chunker.length.boundary.lookback_percent``
+     - ``20``\ (0–50)
+     - Wie weit vor dem idealen Schnittpunkt, als Prozentsatz von ``chunk_size``, nach einer
+       Grenze gesucht werden darf
+   * - ``content_chunker.length.boundary.lookahead_percent``
+     - ``5``\ (0–25)
+     - Wie weit nach dem idealen Schnittpunkt, als Prozentsatz von ``chunk_size``, nach einer
+       Grenze gesucht werden darf
    * - ``content_chunker.max_chunks_per_document``
      - ``1000``
      - Maximale Anzahl von Chunks pro Dokument. Dokumente, die diesen Wert überschreiten, werden
@@ -221,6 +235,27 @@ Einstellungen in system.properties
      - (nicht gesetzt)
      - Der Parameter ``ef_search`` für ANN-Abfragen
 
+.. note::
+
+   Mit ``content_chunker.length.boundary.enabled=true`` (Standardeinstellung) wird
+   ``content_chunker.length.chunk_size`` zu einem Zielwert statt zu einer harten Obergrenze,
+   wobei jeder Schnitt sich innerhalb des Suchfensters zur am besten geeigneten Grenze
+   verschiebt: ein Zeilenumbruch oder Satzende hat Vorrang vor einem Teilsatztrennzeichen oder
+   Leerzeichen, und diese ihrerseits Vorrang vor einem Schriftsystemwechsel. Verschoben wird
+   dabei nur der Schnittpunkt selbst; es geht kein Zeichen verloren, sodass das Zusammenfügen
+   der Chunks eines Dokuments weiterhin exakt dessen Inhalt ergibt. Die Vorwärtssuche kann
+   ``chunk_size`` um bis zu ``content_chunker.length.boundary.lookahead_percent`` überschreiten.
+   Ein zweites, unabhängiges Überschreiten um bis zu 32 Zeichen kann auftreten, wenn ein Schnitt
+   sonst mitten in einem Graphemcluster (ein kombinierendes Zeichen, ein Variationsselektor oder
+   eine durch Zero-Width-Joiner verbundene Emoji-Sequenz) landen würde — dieses ignoriert
+   ``lookahead_percent`` und kann auch bei ``0`` auftreten. Die beiden Überschreitungen treten
+   nie beim selben Schnitt gemeinsam auf; der ungünstigste Fall liegt bei den Standardwerten bei
+   etwa 841 Zeichen. Chunks können außerdem um bis zu ``lookback_percent`` kürzer ausfallen,
+   sodass ein Dokument etwas mehr Chunks als zuvor erzeugen kann (siehe
+   ``content_chunker.max_chunks_per_document``). Setzen Sie
+   ``content_chunker.length.boundary.enabled=false`` oder beide Prozentsätze auf ``0``, um das
+   bisherige exakte Verhalten mit fester Länge wiederherzustellen.
+
 .. note::
 
    Die HNSW-Parameter ``m`` und ``ef_construction`` sind in ``doc.json`` fest codiert

en/15.8/config/search-semantic.rst

@@ -140,10 +140,23 @@ system.properties Settings
      - Chunking method
    * - ``content_chunker.length.chunk_size``
      - ``800``
-     - Number of characters per chunk
+     - Number of characters per chunk (target, see the note below)
    * - ``content_chunker.length.overlap``
      - ``0``
      - Number of characters to overlap between chunks
+   * - ``content_chunker.length.boundary.enabled``
+     - ``true``
+     - Moves each cut to the nearest suitable break within the search window, preferring a line
+       break or sentence end over a clause separator or space, and those over a script change,
+       instead of landing at exactly ``chunk_size`` characters
+   * - ``content_chunker.length.boundary.lookback_percent``
+     - ``20``\ (0-50)
+     - How far before the ideal cut, as a percentage of ``chunk_size``, the boundary search may
+       look for a break
+   * - ``content_chunker.length.boundary.lookahead_percent``
+     - ``5``\ (0-25)
+     - How far after the ideal cut, as a percentage of ``chunk_size``, the boundary search may
+       look for a break
    * - ``content_chunker.max_chunks_per_document``
      - ``1000``
      - Maximum number of chunks per document. Documents that exceed this are marked ``skipped``
@@ -209,6 +222,24 @@ system.properties Settings
      - (unset)
      - The ``ef_search`` parameter for ANN queries
 
+.. note::
+
+   With ``content_chunker.length.boundary.enabled=true`` (the default),
+   ``content_chunker.length.chunk_size`` becomes a target rather than a hard ceiling: each cut
+   moves to the nearest suitable break within the search window, preferring a line break or
+   sentence end over a clause separator or space, and those over a script change. Only the cut
+   point ever moves; no character is dropped, so concatenating a document's chunks still
+   reproduces its content exactly. The forward search can overshoot ``chunk_size`` by up to
+   ``content_chunker.length.boundary.lookahead_percent``; a second, independent overshoot of up
+   to 32 characters can occur when a cut would otherwise land inside a grapheme cluster (a
+   combining mark, a variation selector, or a zero-width-joined emoji sequence) — that one
+   ignores ``lookahead_percent`` and can happen even when it is ``0``. The two overshoots never
+   occur on the same cut; the worst case at the shipped defaults is about 841 characters. Chunks
+   can also come in up to ``lookback_percent`` shorter, so a document may produce slightly more
+   chunks than before (see ``content_chunker.max_chunks_per_document``). Set
+   ``content_chunker.length.boundary.enabled=false``, or both percentages to ``0``, to restore
+   the previous exact fixed-length behavior.
+
 .. note::
 
    The HNSW ``m`` and ``ef_construction`` parameters are hard-coded in ``doc.json``

es/15.8/config/search-semantic.rst

@@ -147,10 +147,23 @@ Configuraciones en system.properties
      - Método de chunking
    * - ``content_chunker.length.chunk_size``
      - ``800``
-     - Número de caracteres por chunk
+     - Número de caracteres por chunk (valor objetivo, véase la nota más abajo)
    * - ``content_chunker.length.overlap``
      - ``0``
      - Número de caracteres que se superponen entre chunks
+   * - ``content_chunker.length.boundary.enabled``
+     - ``true``
+     - Desplaza cada corte hasta el límite más adecuado dentro de la ventana de búsqueda,
+       priorizando salto de línea o fin de frase sobre separador de cláusula o espacio, y estos
+       sobre cambio de escritura, en lugar de cortar exactamente a los ``chunk_size`` caracteres
+   * - ``content_chunker.length.boundary.lookback_percent``
+     - ``20``\ (0-50)
+     - Hasta dónde, antes del punto de corte ideal y como porcentaje de ``chunk_size``, puede
+       retroceder la búsqueda de un límite
+   * - ``content_chunker.length.boundary.lookahead_percent``
+     - ``5``\ (0-25)
+     - Hasta dónde, después del punto de corte ideal y como porcentaje de ``chunk_size``, puede
+       avanzar la búsqueda de un límite
    * - ``content_chunker.max_chunks_per_document``
      - ``1000``
      - Número máximo de chunks por documento. Los documentos que superan este valor se marcan
@@ -221,6 +234,26 @@ Configuraciones en system.properties
      - (sin establecer)
      - El parámetro ``ef_search`` para las consultas ANN
 
+.. note::
+
+   Con ``content_chunker.length.boundary.enabled=true`` (valor predeterminado),
+   ``content_chunker.length.chunk_size`` pasa a ser un objetivo en lugar de un límite estricto:
+   cada corte se desplaza hasta el límite más adecuado dentro de la ventana de búsqueda,
+   priorizando salto de línea o fin de frase sobre separador de cláusula o espacio, y estos sobre
+   cambio de escritura. Solo se desplaza el punto de corte; no se pierde ningún carácter, por lo
+   que concatenar los chunks de un documento sigue reproduciendo exactamente su contenido. La
+   búsqueda hacia adelante puede superar ``chunk_size`` en hasta
+   ``content_chunker.length.boundary.lookahead_percent``. Puede producirse un segundo exceso,
+   independiente, de hasta 32 caracteres cuando un corte caería en medio de un clúster de
+   grafemas (una marca combinante, un selector de variación o una secuencia de emojis unida por
+   un conector de ancho cero; ZWJ); este ignora ``lookahead_percent`` y puede ocurrir incluso con
+   ``0``. Los dos tipos de exceso nunca se producen en el mismo corte; el peor caso con los
+   valores predeterminados es de unos 841 caracteres. Los chunks también pueden acortarse hasta
+   en ``lookback_percent``, por lo que un documento puede producir ligeramente más chunks que
+   antes (véase ``content_chunker.max_chunks_per_document``). Establezca
+   ``content_chunker.length.boundary.enabled=false``, o ambos porcentajes a ``0``, para restaurar
+   el comportamiento anterior de longitud fija exacta.
+
 .. note::
 
    Los parámetros HNSW ``m`` y ``ef_construction`` están codificados de forma fija en

fr/15.8/config/search-semantic.rst

@@ -150,10 +150,24 @@ Réglages dans system.properties
      - Méthode de chunking
    * - ``content_chunker.length.chunk_size``
      - ``800``
-     - Nombre de caractères par chunk
+     - Nombre de caractères par chunk (valeur cible, voir la note ci-dessous)
    * - ``content_chunker.length.overlap``
      - ``0``
      - Nombre de caractères de chevauchement entre les chunks
+   * - ``content_chunker.length.boundary.enabled``
+     - ``true``
+     - Déplace chaque coupure vers la rupture la plus appropriée dans la fenêtre de recherche, en
+       donnant la priorité à un saut de ligne ou une fin de phrase sur un séparateur de
+       proposition ou un espace, puis à ceux-ci sur un changement d'écriture, au lieu de couper
+       exactement à ``chunk_size`` caractères
+   * - ``content_chunker.length.boundary.lookback_percent``
+     - ``20``\ (0-50)
+     - Jusqu'où, avant le point de coupure idéal et en pourcentage de ``chunk_size``, la
+       recherche de rupture peut remonter
+   * - ``content_chunker.length.boundary.lookahead_percent``
+     - ``5``\ (0-25)
+     - Jusqu'où, après le point de coupure idéal et en pourcentage de ``chunk_size``, la
+       recherche de rupture peut avancer
    * - ``content_chunker.max_chunks_per_document``
      - ``1000``
      - Nombre maximal de chunks par document. Les documents qui dépassent cette limite sont
@@ -225,6 +239,27 @@ Réglages dans system.properties
      - (non défini)
      - Le paramètre ``ef_search`` pour les requêtes ANN
 
+.. note::
+
+   Avec ``content_chunker.length.boundary.enabled=true`` (valeur par défaut),
+   ``content_chunker.length.chunk_size`` devient un objectif plutôt qu'un plafond strict : chaque
+   coupure se déplace vers la rupture la plus appropriée dans la fenêtre de recherche, en donnant
+   la priorité à un saut de ligne ou une fin de phrase sur un séparateur de proposition ou un
+   espace, puis à ceux-ci sur un changement d'écriture. Seul le point de coupure est déplacé ;
+   aucun caractère n'est perdu, si bien que la concaténation des chunks d'un document reproduit
+   toujours son contenu exact. La recherche vers l'avant peut dépasser ``chunk_size`` d'au plus
+   ``content_chunker.length.boundary.lookahead_percent``. Un second dépassement, indépendant,
+   pouvant aller jusqu'à 32 caractères peut se produire lorsqu'une coupure tomberait autrement au
+   milieu d'un cluster de graphèmes (une marque combinante, un sélecteur de variante ou une
+   séquence d'emojis liée par un jointeur de largeur nulle ; ZWJ) — celui-ci ignore
+   ``lookahead_percent`` et peut survenir même lorsqu'il vaut ``0``. Les deux types de
+   dépassement ne se produisent jamais sur la même coupure ; le pire cas avec les valeurs par
+   défaut est d'environ 841 caractères. Les chunks peuvent aussi être plus courts d'au plus
+   ``lookback_percent``, si bien qu'un document peut produire légèrement plus de chunks qu'avant
+   (voir ``content_chunker.max_chunks_per_document``). Définissez
+   ``content_chunker.length.boundary.enabled=false``, ou les deux pourcentages à ``0``, pour
+   restaurer le comportement précédent à longueur fixe exacte.
+
 .. note::
 
    Les paramètres HNSW ``m`` et ``ef_construction`` sont codés en dur dans ``doc.json``

ja/15.8/config/search-semantic.rst

@@ -134,10 +134,21 @@ system.properties の設定
      - チャンク分割方式
    * - ``content_chunker.length.chunk_size``
      - ``800``
-     - 1チャンクの文字数
+     - 1チャンクの文字数（目標値。下記の注記を参照）
    * - ``content_chunker.length.overlap``
      - ``0``
      - チャンク間で重複させる文字数
+   * - ``content_chunker.length.boundary.enabled``
+     - ``true``
+     - 各分割位置を検索ウィンドウ内で最も適した区切りへ移動します。改行や文末を節区切りや
+       空白より優先し、それらを書字系の変わり目より優先するため、``chunk_size`` ちょうどの
+       文字数では区切りません
+   * - ``content_chunker.length.boundary.lookback_percent``
+     - ``20``\ （0〜50）
+     - 理想の分割位置より手前側に、``chunk_size`` に対する割合でどこまで区切りを探すか
+   * - ``content_chunker.length.boundary.lookahead_percent``
+     - ``5``\ （0〜25）
+     - 理想の分割位置より後ろ側に、``chunk_size`` に対する割合でどこまで区切りを探すか
    * - ``content_chunker.max_chunks_per_document``
      - ``1000``
      - 1ドキュメントあたりの最大チャンク数。超過したドキュメントは ``skipped`` になります
@@ -200,6 +211,24 @@ system.properties の設定
      - （未設定）
      - ANNクエリの ``ef_search`` パラメーター
 
+.. note::
+
+   ``content_chunker.length.boundary.enabled=true``\ （デフォルト）の場合、
+   ``content_chunker.length.chunk_size`` は上限ではなく目標値になります。各分割位置は
+   検索ウィンドウ内で最も適した区切りへ移動します。改行や文末を節区切りや空白より優先し、
+   それらを書字系の変わり目より優先します。移動するのは分割位置だけで文字が
+   失われることはないため、ドキュメントのチャンクを連結すれば元の内容と完全に一致します。
+   前方探索によって、``chunk_size`` を最大 ``content_chunker.length.boundary.lookahead_percent``
+   分だけ超える場合があります。これとは別に、書記素クラスター（結合文字、異体字セレクター、
+   ゼロ幅接合子で連結された絵文字シーケンスなど）の途中で分割されそうになった場合には、
+   最大32文字の超過が発生することがあります。こちらは ``lookahead_percent`` の影響を受けず、
+   ``0`` に設定していても発生します。2種類の超過が同じ分割位置で同時に発生することはなく、
+   標準設定での最悪ケースは約841文字です。また、チャンクは ``lookback_percent`` 分だけ
+   短くなることもあるため、ドキュメントのチャンク数が従来よりわずかに増える場合があります
+   （``content_chunker.max_chunks_per_document`` を参照）。
+   ``content_chunker.length.boundary.enabled=false`` を設定するか、両方の割合を ``0`` にすると、
+   従来の厳密な固定長の挙動に戻ります。
+
 .. note::
 
    HNSW の ``m`` と ``ef_construction`` パラメーターは ``doc.json`` に固定値

ko/15.8/config/search-semantic.rst

@@ -135,10 +135,23 @@ system.properties 설정
      - 청크 분할 방식
    * - ``content_chunker.length.chunk_size``
      - ``800``
-     - 청크당 문자 수
+     - 청크당 문자 수(목표값, 아래 참고)
    * - ``content_chunker.length.overlap``
      - ``0``
      - 청크 간에 중복시킬 문자 수
+   * - ``content_chunker.length.boundary.enabled``
+     - ``true``
+     - 각 절단 위치를 탐색 범위 내에서 가장 적합한 경계로 이동시키되, 줄바꿈이나 문장 끝을 절
+       구분이나 공백보다 우선하고 이들을 다시 문자 체계 경계보다 우선하여, ``chunk_size`` 문자
+       수에서 정확히 자르지 않도록 합니다
+   * - ``content_chunker.length.boundary.lookback_percent``
+     - ``20``\ (0-50)
+     - 이상적인 절단 위치보다 앞쪽으로, ``chunk_size`` 에 대한 비율로 얼마나 멀리까지 경계를
+       탐색할 수 있는지
+   * - ``content_chunker.length.boundary.lookahead_percent``
+     - ``5``\ (0-25)
+     - 이상적인 절단 위치보다 뒤쪽으로, ``chunk_size`` 에 대한 비율로 얼마나 멀리까지 경계를
+       탐색할 수 있는지
    * - ``content_chunker.max_chunks_per_document``
      - ``1000``
      - 문서당 최대 청크 수. 이를 초과하는 문서는 ``skipped`` 로 표시됩니다
@@ -198,6 +211,23 @@ system.properties 설정
      - (미설정)
      - ANN 쿼리의 ``ef_search`` 파라미터
 
+.. note::
+
+   ``content_chunker.length.boundary.enabled=true``\ (기본값)인 경우,
+   ``content_chunker.length.chunk_size`` 는 상한이 아니라 목표값이 됩니다. 각 절단 위치는 탐색
+   범위 내에서 가장 적합한 경계로 이동하되, 줄바꿈이나 문장 끝을 절 구분이나 공백보다 우선하고
+   이들을 다시 문자 체계 경계보다 우선합니다. 이동하는 것은 절단 위치뿐이며 문자는 손실되지
+   않으므로, 문서의 청크를 이어 붙이면 원본 내용과 정확히 일치합니다. 전방 탐색으로 인해
+   ``chunk_size`` 를 최대 ``content_chunker.length.boundary.lookahead_percent`` 만큼 초과할 수
+   있습니다. 이와는 별도로, 절단 위치가 자소 클러스터(결합 문자, 이형 선택자, 너비 없는 접합자로
+   연결된 이모지 시퀀스 등) 내부에 놓이게 될 경우 최대 32자까지 추가로 초과할 수 있습니다. 이
+   초과는 ``lookahead_percent`` 의 영향을 받지 않으며 ``0`` 으로 설정해도 발생할 수 있습니다. 두
+   종류의 초과는 동일한 절단 위치에서 동시에 발생하지 않으며, 기본값 기준 최악의 경우는 약
+   841자입니다. 또한 청크는 ``lookback_percent`` 만큼 짧아질 수 있어 문서가 이전보다 약간 더 많은
+   청크를 생성할 수 있습니다(``content_chunker.max_chunks_per_document`` 참고). 이전의 정확한
+   고정 길이 동작으로 되돌리려면 ``content_chunker.length.boundary.enabled=false`` 로 설정하거나
+   두 비율을 모두 ``0`` 으로 설정하세요.
+
 .. note::
 
    HNSW의 ``m`` 및 ``ef_construction`` 파라미터는 ``doc.json`` 에 하드코딩되어 있으며