refa: simplify RAPTOR tree clustering and configuration (#17614)

2026-08-05 15:20:30 +08:00 · 2026-08-03 17:46:50 +08:00
parent e290a0d476
commit 3e7cfbe052
32 changed files with 318 additions and 1356 deletions
--- a/web/src/interfaces/database/compilation-template.ts
+++ b/web/src/interfaces/database/compilation-template.ts
@@ -13,7 +13,8 @@ export interface ICompilationTemplateSection {
 export interface ICompilationTemplateRaptorConfig {
  prompt?: string;
  max_token?: number;
-  threshold?: number;
+  clustering_threshold?: number;
+  clustering_ratio?: number;
  rechunk?: boolean;
 }

--- a/web/src/interfaces/request/compilation-template.ts
+++ b/web/src/interfaces/request/compilation-template.ts
@@ -13,7 +13,8 @@ export interface ICompilationTemplateSectionRequest {
 export interface ICompilationTemplateRaptorConfigRequest {
  prompt?: string;
  max_token?: number;
-  threshold?: number;
+  clustering_threshold?: number;
+  clustering_ratio?: number;
  rechunk?: boolean;
 }

--- a/web/src/locales/en.ts
+++ b/web/src/locales/en.ts
@@ -932,9 +932,14 @@ Example: A 1 KB message with 1024-dim embedding uses ~9 KB. The 5 MB default lim
      promptTip:
        'Use the system prompt to describe the task for the LLM, specify how it should respond, and outline other miscellaneous requirements. The system prompt is often used in conjunction with keys (variables), which serve as various data inputs for the LLM. Use a forward slash `/` or the (x) button to show the keys to use.',
      promptMessage: 'Prompt is required',
-      promptText: `Please summarize the following paragraphs. Be careful with the numbers, do not make things up. Paragraphs as following:
-      {cluster_content}
-The above is the content you need to summarize.`,
+      promptText: `Summarize the paragraphs below without inventing facts or changing numbers.
+Output exactly two parts in the same language as the source:
+1. First line: a concise title only.
+2. Following lines: a concise summary of the content.
+Do not output labels, Markdown headings, bullet points, or any other commentary.
+
+Paragraphs:
+{cluster_content}`,
      maxToken: 'Max token',
      maxTokenTip: 'The maximum number of tokens per generated summary chunk.',
      maxTokenMessage: 'Max token is required',
@@ -1900,6 +1905,12 @@ Example: Virtual Hosted Style`,
      maxToken: 'Max token',
      maxTokenRequired: 'Please input max token',
      threshold: 'Threshold',
+      clusteringThreshold: 'Clustering threshold',
+      clusteringThresholdTip:
+        'Sets the percentile used to split clusters by adjacent chunk similarity. Higher values create more cluster boundaries.',
+      clusteringRatio: 'Clustering ratio',
+      clusteringRatioTip:
+        'Sets the maximum number of clusters as a fraction of the input chunks. Lower values produce fewer clusters.',
      rechunkByTreeLeaves: 'Re-chunk by tree leaves',
      rechunkByTreeLeavesTip:
        "Merge each leaf cluster's source chunks into a single replacement chunk. Originals are kept but marked unavailable for retrieval. Only one tree template per group may enable this.",
--- a/web/src/locales/zh.ts
+++ b/web/src/locales/zh.ts
@@ -841,9 +841,14 @@ export default {
        'RAPTOR 常应用于复杂的多跳问答任务。如需打开，请跳转至知识库的文件页面，点击生成 > RAPTOR 开启。详见: https://ragflow.io/docs/dev/enable_raptor。',
      prompt: '提示词',
      promptMessage: '提示词是必填项',
-      promptText: `请总结以下段落。 小心数字，不要编造。 段落如下：
-      {cluster_content}
-以上就是你需要总结的内容。`,
+      promptText: `请在不编造事实、不改变数字的前提下总结以下段落。
+请用与原文相同的语言严格输出两部分：
+1. 第一行：仅输出简洁标题。
+2. 后续行：输出内容的简洁摘要。
+不要输出标签、Markdown 标题、项目符号或其他说明。
+
+段落：
+{cluster_content}`,
      maxToken: '最大token数',
      maxTokenMessage: '最大token数是必填项',
      threshold: '阈值',
@@ -1590,6 +1595,12 @@ NER：使用 spaCy NER 和基于规则的关键词提取来抽取实体和关系
      maxToken: '最大 token 数',
      maxTokenRequired: '请输入最大 token 数',
      threshold: '阈值',
+      clusteringThreshold: '聚类阈值',
+      clusteringThresholdTip:
+        '按相邻数据块相似度分布的百分位决定聚类边界。数值越高，产生的聚类边界越多。',
+      clusteringRatio: '聚类比例',
+      clusteringRatioTip:
+        '设置聚类数量相对于输入数据块数量的最大比例。数值越低，聚类数量越少。',
      rechunkByTreeLeaves: '按树叶重新分块',
      rechunkByTreeLeavesTip:
        '将每个叶簇的源数据块合并为单个替换数据块。原始数据块保留但标记为不可检索。每个分组最多只能有一个树模板启用此功能。',
--- a/web/src/pages/user-setting/compilation-templates/create-next/components/tree-template-fields.tsx
+++ b/web/src/pages/user-setting/compilation-templates/create-next/components/tree-template-fields.tsx
@@ -21,7 +21,8 @@ export function TreeTemplateFields({ index }: TreeTemplateFieldsProps) {
        >
          <Textarea
            placeholder={t('setting.descriptionPlaceholder')}
-            rows={6}
+            rows={8}
+            resize="vertical"
          />
        </RAGFlowFormItem>

@@ -29,12 +30,21 @@ export function TreeTemplateFields({ index }: TreeTemplateFieldsProps) {
          name={`templates.${index}.config.raptor.max_token`}
          label={t('setting.maxToken')}
          max={2048}
-          min={0}
+          min={512}
          step={1}
        />
        <SliderInputFormField
-          name={`templates.${index}.config.raptor.threshold`}
-          label={t('setting.threshold')}
+          name={`templates.${index}.config.raptor.clustering_threshold`}
+          label={t('setting.clusteringThreshold')}
+          tooltip={t('setting.clusteringThresholdTip')}
+          step={0.01}
+          max={1}
+          min={0}
+        />
+        <SliderInputFormField
+          name={`templates.${index}.config.raptor.clustering_ratio`}
+          label={t('setting.clusteringRatio')}
+          tooltip={t('setting.clusteringRatioTip')}
          step={0.01}
          max={1}
          min={0}
--- a/web/src/pages/user-setting/compilation-templates/create-next/schema.ts
+++ b/web/src/pages/user-setting/compilation-templates/create-next/schema.ts
@@ -11,8 +11,9 @@ export const buildSectionSchema = (t: (key: string) => string) =>
 export const buildRaptorConfigSchema = (t: (key: string) => string) =>
  z.object({
    prompt: z.string().optional(),
-    max_token: z.number().min(1, t('setting.maxTokenRequired')),
-    threshold: z.number().min(0).max(1),
+    max_token: z.number().min(512, t('setting.maxTokenRequired')).max(2048),
+    clustering_threshold: z.number().min(0).max(1),
+    clustering_ratio: z.number().min(0).max(1),
    rechunk: z.boolean().optional(),
  });

--- a/web/src/pages/user-setting/compilation-templates/create-next/utils.ts
+++ b/web/src/pages/user-setting/compilation-templates/create-next/utils.ts
@@ -139,7 +139,8 @@ export const buildConfigFromBuiltin = (
      raptor: {
        prompt: builtinRaptor.prompt ?? '',
        max_token: builtinRaptor.max_token ?? 512,
-        threshold: builtinRaptor.threshold ?? 0.1,
+        clustering_threshold: builtinRaptor.clustering_threshold ?? 0.3,
+        clustering_ratio: builtinRaptor.clustering_ratio ?? 0.5,
        rechunk: builtinRaptor.rechunk ?? false,
      },
    };
@@ -205,7 +206,8 @@ export const transformDetailToForm = (
        raptor: {
          prompt: raptor.prompt ?? '',
          max_token: raptor.max_token ?? 512,
-          threshold: raptor.threshold ?? 0.1,
+          clustering_threshold: raptor.clustering_threshold ?? 0.3,
+          clustering_ratio: raptor.clustering_ratio ?? 0.5,
          rechunk: raptor.rechunk ?? false,
        },
      },
--- a/web/src/pages/user-setting/compilation-templates/edit-next/components/tree-template-fields.tsx
+++ b/web/src/pages/user-setting/compilation-templates/edit-next/components/tree-template-fields.tsx
@@ -21,7 +21,8 @@ export function TreeTemplateFields({ index }: TreeTemplateFieldsProps) {
        >
          <Textarea
            placeholder={t('setting.descriptionPlaceholder')}
-            rows={6}
+            rows={8}
+            resize="vertical"
          />
        </RAGFlowFormItem>

@@ -29,12 +30,21 @@ export function TreeTemplateFields({ index }: TreeTemplateFieldsProps) {
          name={`templates.${index}.config.raptor.max_token`}
          label={t('setting.maxToken')}
          max={2048}
-          min={0}
+          min={512}
          step={1}
        />
        <SliderInputFormField
-          name={`templates.${index}.config.raptor.threshold`}
-          label={t('setting.threshold')}
+          name={`templates.${index}.config.raptor.clustering_threshold`}
+          label={t('setting.clusteringThreshold')}
+          tooltip={t('setting.clusteringThresholdTip')}
+          step={0.01}
+          max={1}
+          min={0}
+        />
+        <SliderInputFormField
+          name={`templates.${index}.config.raptor.clustering_ratio`}
+          label={t('setting.clusteringRatio')}
+          tooltip={t('setting.clusteringRatioTip')}
          step={0.01}
          max={1}
          min={0}
--- a/web/src/pages/user-setting/compilation-templates/edit-next/schema.ts
+++ b/web/src/pages/user-setting/compilation-templates/edit-next/schema.ts
@@ -11,8 +11,9 @@ export const buildSectionSchema = (t: (key: string) => string) =>
 export const buildRaptorConfigSchema = (t: (key: string) => string) =>
  z.object({
    prompt: z.string().optional(),
-    max_token: z.number().min(1, t('setting.maxTokenRequired')),
-    threshold: z.number().min(0).max(1),
+    max_token: z.number().min(512, t('setting.maxTokenRequired')).max(2048),
+    clustering_threshold: z.number().min(0).max(1),
+    clustering_ratio: z.number().min(0).max(1),
    rechunk: z.boolean().optional(),
  });

--- a/web/src/pages/user-setting/compilation-templates/edit-next/utils.ts
+++ b/web/src/pages/user-setting/compilation-templates/edit-next/utils.ts
@@ -135,7 +135,8 @@ export const buildConfigFromBuiltin = (
      raptor: {
        prompt: builtinRaptor.prompt ?? '',
        max_token: builtinRaptor.max_token ?? 512,
-        threshold: builtinRaptor.threshold ?? 0.1,
+        clustering_threshold: builtinRaptor.clustering_threshold ?? 0.3,
+        clustering_ratio: builtinRaptor.clustering_ratio ?? 0.5,
        rechunk: builtinRaptor.rechunk ?? false,
      },
    };
@@ -201,7 +202,8 @@ export const transformDetailToForm = (
        raptor: {
          prompt: raptor.prompt ?? '',
          max_token: raptor.max_token ?? 512,
-          threshold: raptor.threshold ?? 0.1,
+          clustering_threshold: raptor.clustering_threshold ?? 0.3,
+          clustering_ratio: raptor.clustering_ratio ?? 0.5,
          rechunk: raptor.rechunk ?? false,
        },
      },