package cn.iocoder.yudao.module.qcreport.service.aiimport.document;
|
|
import java.util.List;
|
|
/**
|
* 一个文件被适配器抽取后的中间结果。
|
* <p>
|
* <b>刻意不是树、也不是 HTML</b>：它只是「这份文件能交给模型的东西是什么」这个更小的问题的答案。
|
* 树要表达版式，HTML 要表达样式，两者都会把「模型能看见什么」放大到不可控；这里只留两个通道，
|
* 迫使下游（提示词构造、调用计划）不必再考虑第三种形态。
|
*
|
* <h3>为什么是双通道而不是一种</h3>
|
* 电子版 PDF / Word / Excel 有真实文本层，抽取成字符串最省 token，模型也读得最准；
|
* 扫描件与照片没有文本层，只能把页面渲染成图交给多模态模型。
|
* 这两条路的调用方式（{@code chat} 与 {@code chatWithImage}）、计费口径、失败模式都不同，
|
* 所以必须在类型上分开，而不是塞进一个字段里靠猜。
|
*
|
* @param channel 通道类型，见 {@link Channel}
|
* @param text TEXT 通道的正文，多页时页间以 {@code --- 第 N 页 ---} 分隔；IMAGES 通道恒为空串
|
* @param images IMAGES 通道的图片，每页一张；TEXT 通道恒为空列表
|
* @param pageCount 页数，用于超限校验与提示文案
|
* @param extractor 实际生效的抽取器标识（如 {@code pdfbox-text}），会写进日志便于排查
|
* @param notes 抽取阶段的软提示，直接进响应的 warnings 展示给用户
|
*/
|
public record QcReportDocumentExtract(
|
Channel channel,
|
String text,
|
List<ImagePart> images,
|
int pageCount,
|
String extractor,
|
List<String> notes) {
|
|
/**
|
* 纵向合并续格的占位标记。
|
* <p>
|
* 它属于「抽取出来的文本长什么样」这条契约，所以和 {@code text} 放在一处，
|
* 由生产者（{@link OfficeImportAdapter}）与解释者（{@code QcReportTemplatePromptBuilder}）
|
* 共用一份，避免两边各写一个字面量后各自漂移。
|
* <p>
|
* 为什么不能留空：{@code w:vMerge} 的续格在 Word 里表示「这一格与上一行是同一个值」，
|
* 但 POI 取出来就是空串。留空的话，模型区分不出「合并续格」与「原件本来就没填」，
|
* 于是整张表看起来是一层平铺的检验项，看不出分组结构。
|
*/
|
public static final String VERTICAL_MERGE_MARK = "↑同上";
|
|
/**
|
* 抽取通道。
|
*/
|
public enum Channel {
|
/** 有文本层，整份文件拼成一段文本，一次模型调用 */
|
TEXT,
|
/** 无文本层（扫描件/照片），逐页转图，每页一次模型调用 */
|
IMAGES
|
}
|
|
/**
|
* IMAGES 通道里的一页图。
|
*
|
* @param bytes 图片字节，执行器负责转成裸 base64
|
* @param mimeType 形如 {@code image/png} 的裸类型，不带 {@code data:} 前缀
|
* @param label 页标签，用于拼错误与提示文案，例如「扫描件.pdf 第 2 页」
|
*/
|
public record ImagePart(byte[] bytes, String mimeType, String label) {
|
}
|
|
/**
|
* 文本通道的工厂。{@code notes} 允许为空表示没有软提示。
|
*/
|
public static QcReportDocumentExtract ofText(String text, int pageCount, String extractor,
|
List<String> notes) {
|
return new QcReportDocumentExtract(Channel.TEXT, text, List.of(), pageCount, extractor, notes);
|
}
|
|
/**
|
* 图片通道的工厂。
|
*/
|
public static QcReportDocumentExtract ofImages(List<ImagePart> images, int pageCount,
|
String extractor, List<String> notes) {
|
return new QcReportDocumentExtract(Channel.IMAGES, "", List.copyOf(images), pageCount,
|
extractor, notes);
|
}
|
|
}
|
