modules.llmAI 模块帮助

本章节包含 modules.llmAI 包中常用「大模型 / 视觉抽取 / 表格智能分析」模块的使用说明和示例，例如：

文本提示词模板化与变量填充（PromptTemplate）
直接调用大模型进行文本生成（LLMNode）
从图片中提取表格（TableDataExtractor）或结构化字段（DictDataExtractor）
对表格数据进行智能分析、清洗与绘图（TableAnalyzer）

PromptTemplate

模块简介与适用场景

PromptTemplate 用于定义包含 {变量} 占位符的提示词模板，并把变量值填充为最终提示词（端口：OutputPrompt）。
变量值来源优先级（高→低）：
- InputValues 端口传入的 SingleResult 或 ResultModel：
  - SingleResult：优先按 UnitResult.name 匹配；再按 UnitResult.title 匹配
  - ResultModel：优先按字段名匹配；再按 Field(title=...) 匹配
- 模块参数 variable_values 字典
- 缺失值按 missing_value_handling 处理（空字符串/报错/保留占位符）
典型适用场景：
- 在 pipeline 中把「项目参数/表单输入/前序模块输出」拼装成可复用提示词；
- 配合 pipeline.add_dict_attribute 把模板变量暴露为 Pipeline 级参数，便于在 UI 中统一配置；
- 配合 LLMNode / TableAnalyzer 实现 “模板化提示词 → LLM 推理” 的流程；
- 直接消费上游 LLMNode.OutputReply``（``ResultModel）的结果，继续拼装下一轮提示词。

端口说明

输入端口 - InputValues：输入变量值（SingleResult 或 ResultModel）。SingleResult 优先按 UnitResult.name 匹配、再按 UnitResult.title 匹配；ResultModel 优先按字段名匹配、再按 Field(title=...) 匹配。若设置了 variable_titles，会优先使用其中定义的标题参与标题匹配。
输出端口 - OutputPrompt：输出填充后的提示词文本（str）。

快速上手示例：使用 variable_values 填充提示词

from gdisdk.modules.llmAI import PromptTemplate

tpl = PromptTemplate(
    mname="Tpl",
    template="请分析 {data_type} 数据，并重点关注 {aspect}。",
    variable_titles={"data_type": "数据类型", "aspect": "关注点"},
)
tpl.variable_values = {"data_type": "沉降监测", "aspect": "异常点与趋势"}
prompt = tpl.execute()

print(prompt)  # -> "请分析 沉降监测 数据，并重点关注 异常点与趋势。"

参数说明

PromptTemplate 参数一览
参数名	类型	默认值	说明
`template`	`str`	`""`	提示词模板，使用 `{var}` 表示占位符。
`variable_values`	`dict[str, Any] \| None`	`{}`	变量值字典（可被 `InputValues` 覆盖）。
`variable_titles`	`dict[str, str] \| None`	`{}`	变量在 UI 中的显示标题；也用于按 `UnitResult.title` 或 `Field(title=...)` 匹配变量。
`placeholder_pattern`	`str`	`r"\{(\w+)\}"`	用于提取模板变量的正则表达式，默认匹配 `{variable_name}` 形式的占位符。
`missing_value_handling`	`Literal["empty","error","keep_placeholder"]`	`"empty"`	缺失变量时的处理策略：空串/抛错/保留 `{var}`。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.llmAI import PromptTemplate, LLMNode

pipe = PipeLine(app_name="PromptToLLM", app_title="模板提示词 → LLM 示例")

tpl = PromptTemplate(
    mname="Tpl",
    template="你是一名岩土工程师，请用简明中文解释：{question}",
    variable_titles={"question": "问题"},
)
llm = LLMNode(mname="LLM", model="qwen-plus")

# 把模板输出连到 LLM 输入
links = tpl.OutputPrompt >> llm.InputPrompt
pipe.add_links(links)

# 把模板变量暴露为 Pipeline 属性，便于在 UI 中配置
pipe.add_dict_attribute(
    attr_name="question",
    module_name="Tpl",
    param_name="variable_values",
    key_name="question",
    attr_title="问题",
)
pipe.set_attributes(question="什么是有效应力原理？")

pipe.run()
reply = llm.OutputReply.data

更多信息

LLMNode

模块简介与适用场景

LLMNode 是一个通用「大模型调用」模块：输入提示词（InputPrompt），执行后会同时提供三类结果：
- execute() 的返回值：ResultModel``（与 ``OutputReply 语义一致）
- OutputReply：封装后的 ResultModel，默认字段名为 reply，可直接接到下游 PromptTemplate.InputValues
- OutputResponse：底层 AgentRunResult``（``AIRunResult），可读取消息历史与 token 使用量等运行信息
典型适用场景：
- 通用文本生成：摘要、改写、扩写、翻译、问答；
- 将 LLM 回复直接作为结构化输入传给下游 PromptTemplate / Agent 类模块；
- 在 response_format={"type": "json_object"} 时获取规范化后的 JSON 字符串回复。

端口说明

输入端口 - InputPrompt：输入提示词（str）。若该端口有数据，会覆盖模块参数 prompt。
输出端口 - OutputReply：输出 ResultModel。默认包含字段 reply；可通过 reply_key_name / reply_key_title 自定义字段名与显示标题。 - OutputResponse：输出 AgentRunResult``（``AIRunResult）。可通过 .output 读取文本回复，通过 .all_messages() 查看完整消息，通过 .usage() 查看 token 使用量。

快速上手示例：最小 LLM 调用

from gdisdk.modules.llmAI import LLMNode

llm = LLMNode(
    mname="LLM",
    prompt="用三句话概括工程勘察报告的主要内容。",
    model="qwen-plus",
    api_key="你的API_KEY",  # 或在 pipeline.llm_key 中统一设置
)
reply_model = llm.execute()
run_result = llm.OutputResponse.data

print(reply_model.reply)  # execute() 直接返回 ResultModel，默认字段为 reply
print(run_result.usage()) # token 使用量等运行信息

参数说明

LLMNode 参数一览
参数名	类型	默认值	说明
`prompt`	`str \| None`	`None`	提示词；若 `InputPrompt` 端口有数据，会覆盖该参数。
`llm_provider`	`Literal["geekai", "siliconflow", "ollama", "openrouter"]`	`"geekai"`	使用的 LLM 提供方。
`model`	`str`	`"qwen-plus"`	模型名称（可在 UI 下拉框选择）。
`temperature`	`float`	`0.1`	采样温度；越大越发散，越小越稳定。
`max_tokens`	`int`	`4096`	输出 token 上限。
`system_prompt`	`str \| None`	`None`	系统提示词（可用于设定角色/领域背景）。
`response_format`	`dict[str, str \| dict] \| None`	`None`	返回格式约束（例如 `{"type": "json_object"}`）。当启用 `json_object` 模式时，回复文本会在内部做一次 JSON 解析与重新序列化，尽量得到更稳定的 JSON 字符串。
`reply_key_name`	`str`	`"reply"`	`OutputReply` 中回复字段的字段名，便于下游 `PromptTemplate` 直接按占位符名消费。
`reply_key_title`	`str \| None`	`None`	`OutputReply` 中回复字段的显示标题；为空时回退到 `reply_key_name`。
`api_key`	`str \| None`	`None`	API Key；若不填，会优先使用 pipeline 的 `llm_key`；或从环境变量中读取。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.llmAI import LLMNode

pipe = PipeLine(app_name="LLMDemo", app_title="LLMNode 示例")
pipe.llm_key = "你的API_KEY"

llm = LLMNode(mname="LLM", model="qwen-plus")
llm.InputPrompt = "把下面这段文字润色为更正式的报告语气：......"

pipe.add_module(llm)
pipe.run()
print(llm.OutputReply.data.reply)

更多信息

TableDataExtractor

模块简介与适用场景

TableDataExtractor 用于从图片中提取结构化表格，输出 TableData``（单表）或 ``TableCollection``（多表，端口：``OutputTables）。
通过 table_configs 配置每个表格的列名、说明、提示词和数据类型；支持用 images_prefix 仅处理指定前缀的图片。
典型适用场景：
- 从扫描件/截图/报表图片中提取表格（检测数据、统计表、材料清单等）；
- 作为数据入口，与后续 filters/operators/statistics 等模块衔接；
- 提取后交给 TableAnalyzer 自动分析/清洗/绘图。

端口说明

输入端口 - InputImages：输入图片路径（FilesPath）。若该端口有数据，会覆盖模块参数 images_path。
输出端口 - OutputTables：输出提取结果（单表为 TableData；多表为 TableCollection）。

快速上手示例：提取单张表

from gdisdk.modules.llmAI import TableDataExtractor

extractor = TableDataExtractor(
    mname="ExtractTable",
    images_path="path/to/images",  # 文件夹或文件列表（按项目约定）
    table_configs=[
        {
            "images_prefix": "table1",  # 可选：只处理文件名以 table1 开头的图片
            "columns": ["Name", "Age", "City"],
            "table_description": "人员信息表",
            "extraction_instructions": "注意区分 0/O、1/l 等易混字符",
            "data_types": {"Age": "int"},
        }
    ],
    vision_model="qwen3-vl-flash",
    api_key="你的API_KEY",
)
table = extractor.execute()
df = extractor.OutputTables.data.dataframe  # TableData.dataframe

参数说明

TableDataExtractor 参数一览
参数名	类型	默认值	说明
`images_path`	`FilesPath \| None`	`None`	图片路径输入；若 `InputImages` 端口有数据，会覆盖该参数。
`table_configs`	`list[dict]`	`[]`	表格提取配置列表（每行代表一个表格）。
`vision_model`	`str`	`"qwen3-vl-flash"`	视觉模型名称（用于表格/图片理解）。
`llm_provider`	`LLMProvider \| str`	`LLMProvider.GEEKAI`	提供方选择。
`temperature`	`float`	`0.1`	生成温度（越小越稳定）。
`max_tokens`	`int`	`4096`	输出 token 上限。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.llmAI import TableDataExtractor, TableAnalyzer

pipe = PipeLine(app_name="ExtractAndAnalyze", app_title="表格提取 → 智能分析示例")
pipe.llm_key = "你的API_KEY"

extract = TableDataExtractor(mname="ExtractTable")
extract.table_configs = [
    {"images_prefix": "table", "columns": ["col1", "col2"], "table_description": "示例表"}
]

analyze = TableAnalyzer(mname="Analyze")
analyze.prompt = "请给出数据质量检查与异常值建议。"

links = extract.OutputTables >> analyze.InputData
pipe.add_links(links)
pipe.run()

print(analyze.OutputInsights.data)

更多信息

DictDataExtractor

模块简介与适用场景

DictDataExtractor 用于从图片中提取 “字段-值” 结构（JSON/dict），输出为 SingleResult``（端口：``OutputSingleResult）。
通过 field_configs 配置要抽取的字段（字段名、显示标题、类型、描述、单位等）。
典型适用场景：
- 从表单/证件/票据中抽取结构化信息（发票号、金额、日期、项目编号等）；
- 抽取后直接作为报告变量写入模板，或与其它模块输出汇总为 SingleResult。

端口说明

输入端口 - InputImages：输入图片路径（FilesPath）。若该端口有数据，会覆盖模块参数 images_path。
输出端口 - OutputSingleResult：输出抽取结果（SingleResult），每个字段对应一个 ``UnitResult``（name/title/value/unit/description）。

快速上手示例：抽取发票关键字段

from gdisdk.modules.llmAI import DictDataExtractor

extractor = DictDataExtractor(
    mname="ExtractInvoice",
    images_path="path/to/invoice_images",
    extraction_description="发票",
    field_configs=[
        {"name": "company_name", "type": "string", "title": "公司名称"},
        {"name": "invoice_number", "type": "string", "title": "发票号"},
        {"name": "amount", "type": "float", "title": "金额", "unit": "元"},
        {"name": "date", "type": "date", "title": "日期"},
    ],
    api_key="你的API_KEY",
)
result = extractor.execute()
print(result.name_values)  # dict[str, Any]

参数说明

DictDataExtractor 参数一览
参数名	类型	默认值	说明
`images_path`	`FilesPath \| None`	`None`	图片路径输入；若 `InputImages` 端口有数据，会覆盖该参数。
`field_configs`	`list[dict]`	`[]`	字段提取配置列表（每行代表一个字段）。
`extraction_description`	`str`	`"文档"`	被抽取对象的类型描述（例如“发票/检测报告/证书”）。
`extraction_instructions`	`str \| None`	`None`	额外抽取指令（可选）。
`vision_model`	`str`	`"qwen3-vl-flash"`	视觉模型名称。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.llmAI import DictDataExtractor

pipe = PipeLine(app_name="ExtractForm", app_title="表单字段抽取示例")
pipe.llm_key = "你的API_KEY"

extract = DictDataExtractor(mname="Extract")
extract.extraction_description = "证书"
extract.field_configs = [
    {"name": "cert_no", "type": "string", "title": "证书编号"},
    {"name": "issue_date", "type": "date", "title": "签发日期"},
]

pipe.add_module(extract)
pipe.run()
print(extract.OutputSingleResult.data)

更多信息

TableAnalyzer

模块简介与适用场景

TableAnalyzer 是一个 “表格智能分析” 模块：输入 TableData / TableCollection / SingleResult，结合自然语言提示词进行分析，并输出：
- OutputInsights：分析结论文本
- OutputProcessedData：处理后的表（可选）
- OutputPlot：绘图文件路径或图片（可选；也支持 base64）
- OutputResponse：结构化元信息（SingleResult）
典型适用场景：
- 自动数据质量检查（缺失、异常、重复、类型）与清洗建议；
- 基于自然语言做自定义统计/解释；
- 自动生成图表并保存到 workspace。

端口说明

输入端口 - InputData：输入数据（TableData / TableCollection / SingleResult）。 - InputPrompt：输入分析提示词（str）。若该端口有数据，会覆盖模块参数 prompt。
输出端口 - OutputInsights：输出分析结论文本（str）。 - OutputProcessedData：输出处理后的数据（TableData 或 TableCollection，可能为 None）。 - OutputPlot：输出图表（文件路径 FilePath 或图片 Picture；当 plot_format="base64" 时通常为 base64 字符串）。 - OutputResponse：输出结构化元信息（SingleResult），包含分析类型、是否产生处理数据/图表、以及 response metadata 等。

快速上手示例：对一张表进行智能分析

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.llmAI import TableAnalyzer

table = TableData(
    {"x": [1, 2, 3, 4], "y": [2.0, 2.2, 3.5, 10.0]},
    name="demo",
    title="示例表",
)

analyzer = TableAnalyzer(
    mname="Analyze",
    input_data=table,
    prompt="请给出描述性统计，并指出可能的异常值。",
    api_key="你的API_KEY",
    plot_format="png",
    plot_save_mode="workspace",
)
insights = analyzer.execute()
plot = analyzer.OutputInsights.data

参数说明

TableAnalyzer 参数一览
参数名	类型	默认值	说明
`input_data`	`TableData \| TableCollection \| SingleResult \| None`	`None`	输入数据；也可通过 `InputData` 端口传入。
`prompt`	`str \| None`	`None`	自然语言分析指令；也可通过 `InputPrompt` 端口覆盖。
`analysis_type`	`AnalysisType \| str`	`CUSTOM_QUERY`	分析类型；常用为自定义查询（用 prompt 驱动）。
`model`	`str`	`"qwen3-coder-flash"`	用于分析/生成的模型。
`enable_search`	`bool`	`False`	是否启用联网搜索（仅部分 provider/model 组合可用；UI 会动态显示）。
`plot_format`	`Literal["png","jpg","pdf","svg","base64"]`	`"png"`	绘图格式；`base64` 会返回 base64 字符串并删除临时图片文件。
`plot_save_mode`	`Literal["workspace","default"]`	`"workspace"`	绘图保存位置策略（建议 workspace，便于在 GDIM 上管理）。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import CsvReader
from gdisdk.modules.llmAI import TableAnalyzer

pipe = PipeLine(app_name="LLMTableAnalyze", app_title="智能表格分析示例")
pipe.llm_key = "你的API_KEY"
pipe.workspace = "workspace_demo"

read_csv = CsvReader(mname="ReadCsv")
read_csv.file = "example.csv"
read_csv.encoding = "auto"

analyze = TableAnalyzer(mname="Analyze")
analyze.prompt = "请进行数据质量检查，并给出可视化建议。"
analyze.plot_format = "png"

links = read_csv.OutputTable >> analyze.InputData
pipe.add_links(links)
pipe.add_module(read_csv)
pipe.add_module(analyze)
pipe.run()

print(analyze.OutputInsights.data)

更多信息