docs: 更新 README 与 API 文档，描述提示词优化链路
- README 新增提示词优化链路章节（流程图 + 特性 + API 说明） - docs/api.md 新增提示词优化接口文档与调用链路 - 更新架构描述：PromptBuilder → PromptOptimizer
This commit is contained in:
+27
-27
@@ -3,7 +3,7 @@
|
||||
## 技术选型
|
||||
|
||||
- **HTTP 框架**：Gin
|
||||
- **管线编排**：[Eino](https://github.com/cloudwego/eino) `compose.Graph` — 四阶段管线，含质检→重生成分支
|
||||
- **管线编排**：[Eino](https://github.com/cloudwego/eino) `compose.Graph` — 三阶段管线，含质检→重优化分支
|
||||
- **AI 组件**：Eino 的 model / tool 组件，统一接口便于替换模型提供商
|
||||
|
||||
## 分层结构
|
||||
@@ -18,7 +18,7 @@ backend/internal/
|
||||
│ ├── generate.go # 生成任务提交 / 查询 / WebSocket
|
||||
│ └── project_style.go # 工程风格 CRUD
|
||||
├── service/ # 业务逻辑层
|
||||
│ ├── pipeline.go # [已有] Eino compose.Graph 编排：PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter
|
||||
│ ├── pipeline.go # [已有] Eino compose.Graph 编排：PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter
|
||||
│ ├── nodes.go # [已有] 管线四个节点的实现（每个节点单一职责）
|
||||
│ ├── types.go # [已有] 管线输入/状态/输出的显式结构体定义
|
||||
│ ├── inference.go # [已有] AI 推理 API 调用封装（当前为 mock 实现）
|
||||
@@ -50,11 +50,11 @@ backend/internal/
|
||||
|
||||
## 多阶段生成管线
|
||||
|
||||
gen2d 的核心生成流程采用 Eino `compose.Graph` 编排的四阶段管线，含质检不通过时的重生成分支。
|
||||
gen2d 的核心生成流程采用 Eino `compose.Graph` 编排的三阶段管线，含质检不通过时的重优化分支。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["PromptBuilder\n(提示词工程)"] --> B["AssetGenerator\n(AI 出图)"]
|
||||
A["PromptOptimizer\n(提示词优化 + 风格合并)"] --> B["AssetGenerator\n(AI 出图)"]
|
||||
B --> C["QualitySupervisor\n(质检)"]
|
||||
C -- pass --> D["FormatAdapter\n(格式适配)"]
|
||||
C -- fail --> A
|
||||
@@ -62,16 +62,16 @@ flowchart LR
|
||||
|
||||
### 各阶段职责
|
||||
|
||||
#### 1. PromptBuilder
|
||||
#### 1. PromptOptimizer
|
||||
|
||||
- **输入**：用户文本 + 素材类型标签 + 工程风格 + 任务风格覆盖 + 技术参数
|
||||
- **输入**：用户文本 + 素材类型标签 + 工程风格 + 任务风格覆盖 + 技术参数 + Tags
|
||||
- **输出**：三段式完整生成提示词
|
||||
- **职责**：
|
||||
1. 解析用户文本，提取核心内容作为【主题】
|
||||
2. 合并工程风格与任务风格覆盖（任务同名键覆盖工程），生成【约束】（含负面提示词）
|
||||
3. 注入素材类型、分辨率等技术参数作为【内容】
|
||||
4. 拼接为最终提示词
|
||||
5. **重试时**：将上次质检的 RejectReason 注入【约束】段，指导 AI 修正问题
|
||||
1. 合并工程风格与任务风格覆盖（任务同名键覆盖工程），转为自然语言风格描述
|
||||
2. 有标签时调用 PromptAgent（LLM）生成规范化三段式提示词
|
||||
3. 无标签时直接拼接原始 Prompt + 技术参数
|
||||
4. **重试时**：将上次质检的 RejectReason 注入输入，指导 LLM 修正问题
|
||||
5. 未配置 LLM API key 时自动回退到模板生成，不阻塞管线
|
||||
|
||||
**风格合并**：
|
||||
|
||||
@@ -81,17 +81,17 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
|
||||
|
||||
工程风格保证同一工程下所有素材风格一致；任务风格仅覆盖需要差异化的键。
|
||||
|
||||
**三段式提示词结构**：
|
||||
**三段式提示词结构**（由 PromptAgent / LLM 生成）：
|
||||
|
||||
```
|
||||
【主题】用户的原始描述核心内容
|
||||
【约束】风格键值对生成的约束条件 + 负面提示词 + [重试时] 上次质检问题：{rejectReason}
|
||||
【内容】素材类型、分辨率、帧数等技术参数
|
||||
【风格】风格描述与视觉特征
|
||||
【技术】素材类型、分辨率、帧数等技术参数
|
||||
```
|
||||
|
||||
#### 2. AssetGenerator
|
||||
|
||||
- **输入**：PromptBuilder 的输出
|
||||
- **输入**：PromptOptimizer 的输出
|
||||
- **输出**：原始生成图片（单张或多张）
|
||||
- **职责**：调用 AI 推理 API 出图。不同素材类型的差异化需求已在上一步注入提示词中。
|
||||
- **接口规范**：统一采用 OpenAI 兼容的 `/v1/images/generations` 格式。多张生成通过 `n` 参数请求，实际支持数量取决于后端模型（如 DALL-E 3 仅支持 `n=1`，需多次调用模拟多张）。
|
||||
@@ -100,7 +100,7 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
|
||||
|
||||
- **输入**：原始生成图片 + 风格配置
|
||||
- **输出**：通过 / 不通过 + 不通过的原因
|
||||
- **职责**：通过视觉模型检查素材是否符合提示词要求与风格约束。不通过时，Graph 分支将 RejectReason 回填到 PipelineState，路由回 PromptBuilder 重新生成（最多 3 次，超过则降级输出）。
|
||||
- **职责**：通过视觉模型检查素材是否符合提示词要求与风格约束。不通过时，Graph 分支将 RejectReason 回填到 PipelineState，路由回 PromptOptimizer 重新生成（最多 3 次，超过则降级输出）。
|
||||
|
||||
#### 4. FormatAdapter
|
||||
|
||||
@@ -128,7 +128,7 @@ type PipelineInput struct {
|
||||
// PipelineState Graph 全局状态，通过 WithGenLocalState 注入
|
||||
type PipelineState struct {
|
||||
Input PipelineInput
|
||||
FinalPrompt string // PromptBuilder 输出的三段式提示词
|
||||
FinalPrompt string // PromptOptimizer 输出的三段式提示词
|
||||
RawImages []GeneratedImage // AssetGenerator 输出的原始图片
|
||||
PassQuality bool // QualitySupervisor 质检结果
|
||||
RejectReason string // 质检不通过原因
|
||||
@@ -146,7 +146,7 @@ type PipelineOutput struct {
|
||||
|
||||
```go
|
||||
const (
|
||||
nodePromptBuilder = "prompt_builder"
|
||||
nodePromptOptimizer = "prompt_optimizer"
|
||||
nodeAssetGenerator = "asset_generator"
|
||||
nodeQualitySupervisor = "quality_supervisor"
|
||||
nodeFormatAdapter = "format_adapter"
|
||||
@@ -160,7 +160,7 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
|
||||
)
|
||||
|
||||
// 添加节点
|
||||
_ = g.AddLambdaNode(nodePromptBuilder, promptBuilderNode,
|
||||
_ = g.AddLambdaNode(nodePromptOptimizer, promptBuilderNode,
|
||||
compose.WithStatePreHandler(promptBuilderPreHandler), // 重试时注入 RejectReason
|
||||
compose.WithStatePostHandler(promptBuilderPostHandler))
|
||||
_ = g.AddLambdaNode(nodeAssetGenerator, assetGeneratorNode,
|
||||
@@ -170,8 +170,8 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
|
||||
_ = g.AddLambdaNode(nodeFormatAdapter, formatAdapterNode)
|
||||
|
||||
// 连线：正常路径
|
||||
_ = g.AddEdge(compose.START, nodePromptBuilder)
|
||||
_ = g.AddEdge(nodePromptBuilder, nodeAssetGenerator)
|
||||
_ = g.AddEdge(compose.START, nodePromptOptimizer)
|
||||
_ = g.AddEdge(nodePromptOptimizer, nodeAssetGenerator)
|
||||
_ = g.AddEdge(nodeAssetGenerator, nodeQualitySupervisor)
|
||||
_ = g.AddEdge(nodeFormatAdapter, compose.END)
|
||||
|
||||
@@ -184,9 +184,9 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
|
||||
if state.RetryCount >= 3 {
|
||||
return nodeFormatAdapter, nil // 超过重试次数，降级输出
|
||||
}
|
||||
return nodePromptBuilder, nil // 重生成
|
||||
return nodePromptOptimizer, nil // 重生成
|
||||
},
|
||||
map[string]bool{nodePromptBuilder: true, nodeFormatAdapter: true},
|
||||
map[string]bool{nodePromptOptimizer: true, nodeFormatAdapter: true},
|
||||
))
|
||||
|
||||
return g, nil
|
||||
@@ -199,13 +199,13 @@ func NewGenerateGraph() (*compose.Graph[PipelineInput, PipelineOutput], error) {
|
||||
|
||||
| 节点 | Lambda 输入→输出 | State 交互 | 职责 |
|
||||
|------|-----------------|-----------|------|
|
||||
| PromptBuilder | `PipelineInput → string` | PreHandler 读取 RejectReason，PostHandler 写入 FinalPrompt | 合并风格 → 生成三段式提示词（重试时注入质检问题） |
|
||||
| PromptOptimizer | `PipelineInput → string` | PreHandler 读取 RejectReason，PostHandler 写入 FinalPrompt | 合并风格 → 生成三段式提示词（重试时注入质检问题） |
|
||||
| AssetGenerator | `string → []GeneratedImage` | PostHandler 写入 RawImages | 调用 AI 推理 API 出图 |
|
||||
| QualitySupervisor | `[]GeneratedImage → bool` | PostHandler 写入 PassQuality + RejectReason + RetryCount | 视觉模型质检 |
|
||||
| FormatAdapter | `[]GeneratedImage → PipelineOutput` | 无 | 格式转换、spritesheet 打包 |
|
||||
|
||||
```go
|
||||
// PromptBuilder 节点：接收输入，输出提示词
|
||||
// PromptOptimizer 节点：接收输入，输出提示词
|
||||
var promptBuilderNode = compose.InvokableLambda(func(ctx context.Context, in PipelineInput) (string, error) {
|
||||
return buildPrompt(in), nil
|
||||
})
|
||||
@@ -263,7 +263,7 @@ func RunPipeline(ctx context.Context, in PipelineInput) (*PipelineOutput, error)
|
||||
| Project | 顶层容器，用户创建的项目 | 1──1 ProjectStyle, 1──N Task |
|
||||
| ProjectStyle | 工程级键值对风格配置，保证同一工程下所有素材风格一致 | 属于 Project |
|
||||
| Task | 工程下的单次生成请求，包含用户文本、素材类型、任务风格覆盖、技术参数、状态、结果 | 属于 Project, 1──N Asset |
|
||||
| Prompt | PromptBuilder 输出的三段式提示词（主题+约束+内容），管线中间产物，不持久化 | 由 Task 生成 |
|
||||
| Prompt | PromptOptimizer 输出的三段式提示词（主题+约束+内容），管线中间产物，不持久化 | 由 Task 生成 |
|
||||
| Asset | 生成结果素材，关联到任务，包含 URL、元数据（分辨率、帧数、格式） | 属于 Task |
|
||||
|
||||
ER 关系图与外键约束详见 [数据存储 — ER 关系](database.md#er-关系)。
|
||||
@@ -300,7 +300,7 @@ type TaskStyle struct {
|
||||
finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
|
||||
```
|
||||
|
||||
任务同名键覆盖工程风格，由 PromptBuilder 节点在生成提示词时执行合并。
|
||||
任务同名键覆盖工程风格，由 PromptOptimizer 节点在生成提示词时执行合并。
|
||||
|
||||
## 缓存层
|
||||
|
||||
|
||||
Reference in New Issue
Block a user