SeaTunnel AI CLI 技术指南自然语言生成生产级数据管道配置【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnelSeaTunnel AI CLI 是 Apache SeaTunnel 仓库内置的 AI 命令行工具seatunnel-cli模块它把用自然语言描述数据同步任务直接转化为经过校验、可一键执行的 SeaTunnel HOCON 配置文件。本文基于 overview.md 展开结合仓库源码讲解其安装配置、多智能体生成流程、连接器知识库、分层校验体系、会话记忆机制与模型基准评测读完你可以独立完成从安装、接入 LLM Provider 到用/check、/run完成一次真实数据同步的全流程操作并理解其Ground, dont trust的底层设计哲学。一、AI CLI 是什么SeaTunnel AI CLI 的核心价值在于用英文或中文自然语言描述数据同步任务即可获得一份生产可用的 HOCON 配置并且这份配置不是一次性生成的死文件——它附带自动校验validation、错误修复error repair与一键执行one-click execution能力。以官方示例为例在交互式会话中输入 SeaTunnel Sync the users table from MySQL to S3 as Parquet files ⚙️ Generating SeaTunnel config... ✅ Validating config (round 1)... Generated SeaTunnel Config Config saved to: .data/last_job.confAI CLI 以seatunnel-cli模块的形式存在于 SeaTunnel 主仓库中并被打包进标准发行版distribution。它有两种启动方式从发行版安装后通过bin/seatunnel-ai.sh启动首次运行会自动安装 Python 依赖从源码通过 pip 安装后以seatunnel命令启动。从源码安装的目录结构见 seatunnel-cli/README.md其中seatunnel_cli/包内含cli.py交互终端入口、agents.py多智能体编排核心、connectors.py连接器知识库、llm_provider.py多 Provider 抽象、memory.py会话与记忆等核心模块。Key Capabilities 一览能力说明自然语言转配置支持英文与中文输入输出完整的 HOCON 配置多 Provider LLMAWS Bedrock含通过bedrock-mantle端点接入的 OpenAI 系模型、Anthropic API、OpenAI 及兼容 API、OrcaRouter AI 网关多智能体流水线Planner → Config Generator → Validator → 自动修复最多 3 轮纠错连接器知识150 连接器的完整选项规则与取值约束从运行中的引擎实时解析或使用随包分发的元数据校验与修复本地检查 引擎--check/dry-run LLM 驱动的诊断修复/check或/run失败时触发会话与记忆多轮优化、持久化会话、连接信息记忆凭据永不落盘存储与其他 AI 工具的关系AI CLI 是内置、与运行时深度集成的工具仓库还提供了互补的外部工具位于 SeaTunnel Tools 生态中详见 SeaTunnel SkillClaude IDE 级辅助集成、SeaTunnel MCP Server面向 LLM 的 SeaTunnel 资源程序化访问与 x2seatunnel配置格式转换。本文聚焦 AI CLI 本身后续章节逐层深入。二、安装与 LLM Provider 配置2.1 前置条件Python 3.10推荐 3.11 或 3.12操作系统macOS、Linux 或 Windows WSL至少一种 LLM Provider 凭据AWS Bedrock— AWS 凭据profile、环境变量或 IAM roleAnthropic API—ANTHROPIC_API_KEYOpenAI API或兼容 API—OPENAI_API_KEYOrcaRouter—ORCAROUTER_API_KEY可选一个 SeaTunnel 安装用于引擎级校验与任务执行2.2 安装方式方式一从 SeaTunnel 发行版安装推荐。Shell 包装脚本会在首次运行时自动安装 Python 依赖# 首次运行 —— 自动安装依赖并启动交互式初始化 bin/seatunnel-ai.sh --init # 初始化之后直接启动 bin/seatunnel-ai.shSEATUNNEL_HOME会自动被设置为发行版根目录。在发行版 tar 包中CLI 位于cli/seatunnel_cli/向上两级即可自动探测到发行版根目录作为SEATUNNEL_HOME详见 seatunnel-cli/README.md 中的目录结构说明。方式二从源码安装cd seatunnel-cli bash setup.sh # 安装全部 provider 开发工具 seatunnel --init # 交互式 provider 配置也可以按需手动安装pyproject.toml中定义的 extraspip install -e .[bedrock] # AWS Bedrock pip install -e .[anthropic] # Anthropic API pip install -e .[openai] # OpenAI API / OrcaRouter共用 openai 包 pip install -e .[all] # 全部 provider pip install -e .[dev] # 开发模式全部 provider pytest、ruff2.3 配置 Provider环境变量方式API Key只从环境变量读取从不写入配置文件cli.py中的初始化向导也明确遵循这一原则。四种 Provider 的配置如下# Option A: AWS Bedrock默认 export AI_PROVIDERbedrock export AWS_REGIONus-east-1 # Option A2: Bedrock 上的 OpenAI 系模型bedrock-mantle export AI_PROVIDERbedrock-mantle export OPENAI_MODELopenai.gpt-5.6-terra # Option B: Anthropic API export AI_PROVIDERanthropic export ANTHROPIC_API_KEYsk-ant-... # Option C: OpenAI 或兼容 API export AI_PROVIDERopenai export OPENAI_API_KEYsk-... # export OPENAI_BASE_URLhttps://... # Azure OpenAI、DeepSeek、本地 vLLM 等 # Option D: OrcaRouter AI 网关 export AI_PROVIDERorcarouter export ORCAROUTER_API_KEYorc_... # export ORCAROUTER_MODELorcarouter/auto # provider/model 命名空间 # export ORCAROUTER_SMALL_FAST_MODELorcarouter/auto完整的环境变量清单含默认值见 seatunnel-cli/README.md 的环境变量表核心项包括变量必填默认值说明AI_PROVIDER否bedrockbedrock/bedrock-mantle/anthropic/openai/orcarouterOPENAI_BASE_URL否--兼容 OpenAI 协议的自定义端点OPENAI_ECHO_REASONING_CONTENT否true对 DeepSeek、GLM thinking 等推理模型回放reasoning_contentSEATUNNEL_HOME否自动探测SeaTunnel 安装目录用于连接器元数据、/check、/runSEATUNNEL_API_BASE否http://localhost:5801SeaTunnel REST API 端点SEATUNNEL_CLI_DATA否cli-package/.data/会话、记忆、配置的存储目录2.4 两个值得注意的 Provider 细节OrcaRouter AI 网关。OrcaRouter 是一个 OpenAI 兼容的 AI 网关通过单一端点https://api.orcarouter.ai/v1暴露 Claude、GPT、Gemini、DeepSeek、Qwen 等多种模型。模型 ID 采用provider/model命名空间如deepseek/deepseek-v4-pro特殊的orcarouter/auto模型会自动按请求分级选路。由于它走 OpenAI Chat Completions 协议因此完整支持 CLI 内部的工具调用循环规划期连接器查询、流式输出、多轮会话以及推理内容的回放。bedrock-mantleBedrock 上的 OpenAI 系模型。部分 Bedrock 上的 OpenAI 模型如openai.gpt-5.6-terra、openai.gpt-5.6-sol不在 Bedrock 基础模型目录中只支持专用bedrock-mantle端点上的 OpenAI Responses API——常规的bedrockProviderConverse API和openaiProviderChat Completions都够不到它们。该 Provider 的约定如下端点https://bedrock-mantle.{region}.api.aws/openai/v1必须使用模型专属的openai/v1路径鉴权通过aws-bedrock-token-generator从 AWS 凭据自动派生短期 bearer token每 30 分钟刷新一次不落盘任何长效 key数据保留每个请求都携带storefalseBedrock 不会在服务端保留你的提示词与生成的配置服务默认会保留 30 天参数这些模型拒绝temperature参数Provider 从不发送它因此任何配置的 temperature 值都不会生效错误截断incomplete、失败与拒绝的响应会抛出显式错误而不是作为正常回答返回。该 Provider 同样完整支持工具调用循环与多轮会话包括工具调用之间的模型推理输出回放。安装方式pip install -e .[bedrock-mantle]需要 openai SDK 2.45 与 AWS token 生成器。三、快速上手生成第一条数据管道3.1 单次Single-shot模式seatunnel Sync MySQL users table to S3 Parquet seatunnel 从 Kafka 读取订单数据写入 ClickHouse -o my_job.conf第二条命令用-o把生成的配置保存到my_job.conf。命令行还支持--provider、--model、--fast-model覆盖 Provider 与模型例如seatunnel Read CSV files and write to Elasticsearch --provider openai --model gpt-4o完整 CLI 参数见 seatunnel-cli/README.md。3.2 交互式Interactive模式直接运行seatunnel进入 REPL支持流式输出、命令历史、会话持久化与多轮对话 SeaTunnel Sync PostgreSQL orders to Doris Generated SeaTunnel Config Config saved to: .data/last_job.conf SeaTunnel Add a filter to only include orders where amount 100 Generated SeaTunnel Config (updated) SeaTunnel /check [1] Local validation: PASS [2] Engine --check: PASS Dry-run PASSED — Config is ready to execute. SeaTunnel /run Job submitted: 1234567890 (orders-sync) Status: FINISHED生成后的配置会自动保存到.data/last_job.conf可通过SEATUNNEL_CLI_DATA覆盖目录。3.3 常用交互命令命令说明/check校验最新配置失败时自动诊断并修复/run通过 REST API 或seatunnel.sh执行失败时自动修复/connectors列出可用的 source、sink 与 transform/remember text保存非敏感事实主机、端口、数据库名/sessions、/resume列出与恢复历史会话/save path保存配置到自定义路径/memory、/forget、/new、/clear查看/删除记忆、开新会话、清空历史3.4 高质量输出的小技巧在提示词中包含连接信息host、port、database、table产出的配置可直接运行而不是充满占位符明确表述批式 vs 实时意图one-off full copy vs capture changes continuously这决定 BATCH/STREAMING 模式与 CDC 连接器的选择凭据默认占位符化生成的配置引用${MYSQL_PASSWORD}风格变量/run前先 export 对应环境变量对于模型可测得的弱项场景条件路由、PostgreSQL-CDC 前置条件、Doris/StarRocks 选项——见 benchmark在投入生产前人工复核生成的配置。四、多智能体设计为什么不是一次 LLM 调用SeaTunnel 配置生成本质是一个领域 DSL 问题用朴素的prompt in, config out单次调用无法可靠处理原因在于详见 design.md150 连接器、每个 20–50 个选项——没有任何模型能完整、实时地掌握每个选项的名称与类型条件选项依赖——例如仅文本格式可用的选项在format PARQUET时是运行时错误DAG 连线语义——plugin_output/plugin_input标签必须在 source/transform/sink 块之间精确配对模式推断——CDC 源要求 STREAMING有界数据源不应携带仅流式可用的选项。因此 CLI 用权威连接器元数据为模型落地grounding对每个候选配置做校验并用真实错误反馈修复失败项。agents.py中的Orchestrator类正是这一流程的编排者agents.py它协调 Planner → Config → Validator → Fix 的循环最多 3 轮纠错。4.1 完整流水线图User input (natural language) │ ▼ ┌─────────────────┐ ┌──────────────────────┐ │ Planner Agent │───▶│ Connector Knowledge │ │ (intent │◀───│ Base (tools) │ │ clarification)│ └──────────────────────┘ └────────┬────────┘ │ structured plan ▼ ┌─────────────────┐ │ Config Agent │ Generate HOCON config └────────┬────────┘ ▼ ┌─────────────────┐ ┌──────────────────────┐ │ Validator Agent │───▶│ Local validation │ │ │ │ engine --check │ └────────┬────────┘ └──────────────────────┘ │ PASS ── Yes ─▶ Output auto-save │ No (max 3 rounds) ▼ ┌─────────────────┐ │ Fix Agent │ Correct errors, re-validate └─────────────────┘ /check or /run failure at any later point ▼ ┌─────────────────┐ │ Repair Agent │ Diagnose real engine/runtime errors, patch config └─────────────────┘各 Agent 职责源码实现于 agents.pyPlannerPLANNER_SYSTEMagents.py对意图分类——新管道输出PLAN:、提问/诊断输出CHAT:还是错误诊断选择连接器仅在没有合理默认值时才通过ask_user工具追问澄清问题。它内置了合理的默认假设parallelism2、job.mode 按上下文推断、标准端口等并通过route_connectors→get_connector_info→list_connectors等工具见TOOLS定义agents.py在规划期实时查询连接器知识库Config AgentCONFIG_SYSTEM_TEMPLATE基于注入提示词的连接器元数据编写 HOCON强调最小化原则只含必选与关键可选选项、条件选项必须匹配触发条件、严禁编造选项名ValidatorVALIDATOR_SYSTEM先做确定性本地校验validate_hocon再做 LLM 语义审查二者结合Fix/Repair Agents接收真实错误文本——生成期的校验发现或/check、/run之后的真实引擎堆栈——在现有配置上打补丁而非从头重写。修复提示词明确要求Keep ALL existing config values. Only add/change the minimum needed见 cli.py 的 repair_system。4.2 Skill 驱动的提示词增强从源码看流程中还有一层Phase 1.5process_user_input在 Planner 产出结构化计划后会调用SkillRouter.match与SkillExecutoragents.py把匹配到的场景剧本Skill SOP与用户输入、记忆、连接器元数据一起组装成富化提示词。seatunnel_cli/skills/目录下预置了 8 个 Skill SOPbatch_sync.md批式同步、cdc_realtime.mdCDC 实时、conditional_routing.md条件路由、cross_database.md跨库、data_quality.md数据质量、file_etl.md文件 ETL、multi_pipeline.md多管道、transform_chain.md转换链。五、连接器知识库Ground, dont trustCLI 用两级解析保证选项知识准确而不依赖人工维护的提示词文本运行时 API——运行中 SeaTunnel 引擎的 option-rules 端点始终最新随包元数据——connector_metadata.json通过反射从引擎导出并随 CLI 分发包含 source/sink/transform 的必选/可选选项、条件组与取值约束。提示词是按请求组装的只注入 Planner 选中连接器的元数据条件选项被显式归组到触发条件下仅当format text时包含——这是对发明/错位选项最有效的一招。fetch_connector_metadata、validate_connector_options、format_metadata_for_prompt等函数是这一机制的代码入口agents.py 从 connectors.py 导入。在它之上叠加三层生成策略Skill SOPs场景剧本批式同步、CDC 实时、多管道……Golden Examples常见组合的已验证可用配置仓库中见seatunnel_cli/golden_examples/fake_source_console.md、jdbc_console.md、kafka_clickhouse.md、mysql_cdc_starrocks.mdConnector Metadata权威选项规则运行时元数据导出命令为bin/seatunnel-metadata-export.sh需要运行中的引擎或seatunnel --export-metadata。注意没有SEATUNNEL_HOME时 CLI 仍可基于 LLM 知识生成配置但/check、/run与运行时连接器元数据将不可用。六、分层校验流水线阶段方法能捕获的问题1. 本地HOCON 语法、结构、必选选项对照元数据、路由标签配对、未解析的${VAR}占位符字段感知file_name_expression中的${now}等引擎模板变量豁免、安全检查语法错误、缺失/未知选项、连线错误2. 引擎 dry-runseatunnel.sh --check/--dry-run static—— 引擎真实的解析路径插件可加载性、选项类型、未知键、DAG 拓扑3. 执行/run走 REST API 或seatunnel.sh一切运行时问题连通性、Schema、CDC 前置条件每一层都是上一层的严格超集任何一层失败都会把该层的真实错误输出喂给修复循环。本地校验的代码实现值得一看validate_hoconagents.py它实际做了基础结构检查缺失env/source/sink块、花括号不匹配HOCON 语法解析基于 pyhocon对重复连接器名如两个Jdbc块走原始文本的括号计数路径避免 pyhocon 合并连接器必选选项与条件不匹配检查_check_conditional_mismatches若配置中出现了条件选项但其触发条件未满足直接报错——这是运行时类型不匹配失败的根源路由标签配对校验_validate_routing_pairs检查plugin_output/plugin_input是否一一对应重复 output 报错、无主 input 报错、孤立 output 告警STREAMING 模式检查流式任务应设置env.checkpoint.interval如 10000否则告警安全与占位符检查硬编码密码告警未解析的环境变量报错。占位符豁免是字段感知的——引擎模板变量file_name_expression中的${now}/${uuid}/${transactionId}partition_dir_expression中的${k0}/${v0}等在其他字段URL、凭据、路径中出现时仍会被当作普通环境变量诊断。引擎级校验由dry_run_configagents.py实现Phase 1 本地校验 → Phase 2 定位seatunnel.sh --check写入临时文件并执行30 秒超时→ Phase 3 尝试 REST API 校验。七、会话与记忆多轮优化与安全默认AI CLI 支持跨会话记忆用于提升配置准确度详见 seatunnel-cli/README.md项目上下文——表名、数据库名、常见模式偏好——parallelism、format、语言偏好。记忆存储于 CLI 数据目录下的memory.json。/remember添加事实、/memory查看、/forget删除。记忆会被注入到 Planner 与 Config Agent 的系统提示词中_build_planner_system/_build_config_system见 agents.py。安全默认贯穿始终这是设计原则之一生成的配置对所有凭据使用${ENV_VAR}占位符/remember拒绝含密码、API Key、token 等凭据值的内容_cmd_remember中MemoryStore.add返回None即拒绝见 cli.py会话存储对凭据脱敏memory.py中的_redact_conversation_history、redact_credentials发送给 LLM 的配置在修复前会先把凭据替换为${_CRED_N_}占位符、LLM 返回后再还原_replace_creds_with_placeholders/_restore_creds_from_placeholderscli.py全局日志过滤器_SecretRedactFilter会从日志中脱敏 API Key、AWS Key、password 等模式cli.py/run执行前必须显式输入yes确认防止误写生产库_run_configcli.py。此外Orchestrator还做了上下文窗口管理_trimmed_historyagents.py超过 24 条消息时较旧的消息被压缩为一条摘要含脱敏最近 20 条保留原文且工具调用对assistant toolUse user toolResult永不被拆散。八、模型基准评测Measured, Not Assumed架构的效果由专门的基准评测验证详见 benchmark.md100 个任务、三层判定门含对 Docker 化数据源的真实执行、跨 7 个主流 LLM。评测结果直接驱动改进路线图连接器知识注入、结构化错误解析任何对提示词或元数据的改动都能在同一套任务集上做 A/B 度量。8.1 方法论要点任务集100 个任务——20 简单单 source→sink、45 中等类型映射、CDC、转换链、多表、35 复杂多源 DAG、扇出、条件路由——覆盖 12 类 ETL 场景含 10 个中文提示词和 18 个针对已知 LLM 失败模式条件选项误用、BATCH/STREAMING 推断、路由标签连线的规则探针判定门与 CLI 自身 check → dry-run → run 流水线一一对应L1 静态HOCON 解析 连接器元数据 断言——捕获语法、连接器选错、缺失选项L3 真实执行在官方apache/seatunnel镜像上对真实 MySQL/PostgreSQL/Kafka/ClickHouse/Elasticsearch 运行任务批式看退出码流式看 60 秒健康度——捕获一切看起来对但跑不起来的问题修复循环失败时把该门失败的真实错误输出喂给 CLI 自带的修复 Agent最多 3 轮所有判定都是确定性的不用 LLM 当裁判。注意下述结果为 2026 年 7 月针对 seatunnel-cli v0.1.0commit59ada4ec0、模型由 AWS Bedrock 提供服务测得。模型与 CLI 持续演进准确率会漂移请以重新运行的结果为准。8.2 核心结论静态排名在真实执行下反转模型静态门L1真实执行L1L3Claude Opus 4.889%第 385%第 1GPT-5.6 Sol90%第 281%第 2GPT-5.6 Terra93%第 174%第 3静态第一名写出的配置看起来对却在运行时失败静态→真实衰减 −20pp静态第三名写出的配置能跑衰减 −6pp。看起来正确与真的能跑是两种不同的模型能力——这正是该基准要真实执行配置的原因也提醒我们对仅基于静态检查的准确率声明保持审慎。8.3 模型选型指南场景推荐原因交互使用用户在等GPT-5.6 Sol / Terra快25–58s/任务、综合准确率高无人值守 / 批量生成Claude Opus 4.8首次尝试通过率最高输出最可能不改就跑预算敏感的回归测试Qwen3-Coder-Next成本最低档适合冒烟测试而非生产生成自动修复工作流避免 DeepSeek V3.2测量中修复成功率为零8.4 已知弱项场景所有模型有 13 个任务对前 3 名模型全部失败。如果你的管道命中以下形态生产使用前请人工复核配置场景失败根因Doris / StarRocks sink连接器选项知识缺口fenodes、load ports、save modesPostgreSQL-CDC缺失前置条件replication slots、publications未反映到配置中条件路由一个源按谓词拆到多个 sinkplugin_output/plugin_input与并行 SQL transform 的连线宽 DAG5 块、混合 transform标签配对与块排序错误这些聚类是工程目标而非永久限制正在通过连接器元数据注入与 golden-example 覆盖来解决并用同一套基准验证改进。8.5 修复循环的实测有效性把真实引擎错误喂回修复 Agent恢复了 47% 的运行时失败前 3 名模型合计。同一模型修复结构化校验错误的速度约为修复原始 Java 堆栈的2 倍——这证明结构化错误解析而非更聪明的模型是修复循环下一步杠杆率最高的改进点。8.6 自行运行基准基准工具随主仓库分发位于seatunnel-cli/benchmark/100 个声明式任务、分层判定门、Docker 数据环境、报告生成器详见其 READMEcd seatunnel-cli # 凭据走 Provider 标准环境变量 export OPENAI_API_KEYsk-... # 或 ANTHROPIC_API_KEY / AWS 凭据 # 一条命令装依赖、环境预检、运行、出报告 ./benchmark/run_benchmark.sh --provider openai --model gpt-4o # 多模型对比 ./benchmark/run_benchmark.sh --models benchmark/models.json # 可选更深判定门 # L2引擎 dry-run—— 将 SEATUNNEL_HOME 指向 dev 分支构建 # L3真实执行—— docker compose -f benchmark/docker/docker-compose.yml up -d --wait缺失基础设施会优雅降级没有引擎或 Docker 时得到静态门L1报告无法执行的判定门会从所有通过率分母中剔除并在摘要中标出保证不同机器上的结果不会被静默比较。每份报告都带有被测 CLI 版本与 git commit 戳可在新构建上重跑同一模型来度量任何提示词/元数据/修复逻辑改动的影响。九、设计原则总结综合 design.md 与源码实现AI CLI 的四大设计原则是Ground, dont trust落地而非信任提示词中的每个连接器事实都来自引擎元数据而非模型记忆Validate deterministically, repair with the LLM确定性校验、LLM 修复判定来自解析器与引擎LLM 只负责生成与修复从不评判正确性Real errors are the best prompts真实错误是最好的提示词修复 Agent 收到的是真实的校验输出与堆栈实测证实结构化、具体的错误远比原始噪声更容易修复Security by default默认安全生成的配置对所有凭据使用${ENV_VAR}占位符会话存储脱敏敏感信息/remember拒绝敏感值。这套设计使得自然语言 → 生产级 SeaTunnel 配置从演示走向可用连接器知识让它不编造选项分层校验让它不输出坏配置真实错误反馈让它能自我修复而基准评测让每一次改进都有据可依。如果想进一步深入推荐依次阅读 Quick Start、Design 与 Model Benchmark并结合 seatunnel-cli/README.md 与seatunnel-cli/seatunnel_cli/下的源码逐行对照验证。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考