326 lines
6.9 KiB
Markdown
326 lines
6.9 KiB
Markdown
# 🚀 TraceStudio v2.0 高级功能快速参考
|
||
|
||
## 核心概念（5分钟了解）
|
||
|
||
### 1️⃣ 特殊节点
|
||
|
||
| 节点 | 作用 | 特点 |
|
||
|------|------|------|
|
||
| **InputNode** | 工作流入口 | 将全局上下文映射为输出端口 |
|
||
| **OutputNode** | 工作流出口 | 收集结果并返回 |
|
||
| **FunctionNode** | 可复用函数 | 封装子工作流 |
|
||
|
||
### 2️⃣ 连线分类
|
||
|
||
```
|
||
粗线 (━━━) = 数组类型 edgeType: "array"
|
||
细线 (——) = 标量类型 edgeType: "scalar"
|
||
```
|
||
|
||
### 3️⃣ 维度转换
|
||
|
||
```
|
||
升维 数组→单个元素 [1,2,3] → execute 3× → [r1,r2,r3]
|
||
降维 多线→数组 a+b → [a,b]
|
||
广播 单个→数组 5 → [5,5,5]
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 示例 1：简单流水线
|
||
|
||
```python
|
||
from app.core.advanced_workflow_executor import AdvancedWorkflowExecutor
|
||
|
||
nodes = [
|
||
{"id": "input", "type": "InputNodeImpl"},
|
||
{"id": "map", "type": "ArrayMapNode", "params": {"multiplier": 2}},
|
||
{"id": "output", "type": "OutputNodeImpl"}
|
||
]
|
||
|
||
edges = [
|
||
{"source": "input", "sourcePort": "values", "target": "map", "targetPort": "values"},
|
||
{"source": "map", "sourcePort": "mapped", "target": "output", "targetPort": "input"}
|
||
]
|
||
|
||
executor = AdvancedWorkflowExecutor()
|
||
success, report = await executor.execute(nodes, edges, {"values": [1,2,3]})
|
||
# 输出: [2, 4, 6]
|
||
```
|
||
|
||
### 示例 2：创建函数节点
|
||
|
||
```python
|
||
from app.core.advanced_nodes import WorkflowPackager
|
||
|
||
# 验证
|
||
valid, error = WorkflowPackager.validate_function_workflow(sub_nodes, sub_edges)
|
||
|
||
# 打包
|
||
func_def = WorkflowPackager.package_as_function(
|
||
node_id="my_func",
|
||
nodes=sub_nodes,
|
||
edges=sub_edges,
|
||
display_name="我的函数"
|
||
)
|
||
|
||
# 使用
|
||
main_nodes = [..., func_def, ...]
|
||
await executor.execute(main_nodes, main_edges)
|
||
```
|
||
|
||
### 示例 3：维度转换
|
||
|
||
```python
|
||
# 升维（数组遍历）
|
||
edges = [{
|
||
"source": "array_node",
|
||
"target": "scalar_node",
|
||
"edgeType": "array",
|
||
"dimensionMode": "expand" # 自动遍历
|
||
}]
|
||
|
||
# 降维（多线打包）
|
||
edges = [
|
||
{"source": "n1", "target": "concat", "targetPort": "arrays"},
|
||
{"source": "n2", "target": "concat", "targetPort": "arrays"}
|
||
]
|
||
# 自动打包为 [value1, value2]
|
||
```
|
||
|
||
---
|
||
|
||
## 10 个内置节点
|
||
|
||
### 数组操作
|
||
|
||
| 节点 | 输入 | 输出 | 说明 |
|
||
|------|------|------|------|
|
||
| `ArrayMapNode` | Array | Array | `[1,2,3]` ×2 → `[2,4,6]` |
|
||
| `ArrayFilterNode` | Array | Array | `[1,2,3,4]` >2 → `[3,4]` |
|
||
| `ArrayReduceNode` | Array | Scalar | `[1,2,3]` sum → `6` |
|
||
| `ArrayConcatNode` | Array[] | Array | `[[1,2],[3,4]]` → `[1,2,3,4]` |
|
||
| `ArrayZipNode` | Array×2 | Array | `[1,2]` zip `[a,b]` → `[[1,a],[2,b]]` |
|
||
| `BroadcastNode` | Scalar | Array | `5` ×3 → `[5,5,5]` |
|
||
|
||
### 特殊节点
|
||
|
||
| 节点 | 用途 |
|
||
|------|------|
|
||
| `InputNodeImpl` | 工作流入口 |
|
||
| `OutputNodeImpl` | 工作流出口 |
|
||
| `FunctionNodeImpl` | 函数节点基类 |
|
||
|
||
### 控制流
|
||
|
||
| 节点 | 功能 |
|
||
|------|------|
|
||
| `ConditionalBranchNode` | if-then-else（部分实现） |
|
||
|
||
---
|
||
|
||
## API 参考
|
||
|
||
### AdvancedWorkflowExecutor
|
||
|
||
```python
|
||
executor = AdvancedWorkflowExecutor(user_id="user1")
|
||
|
||
# 执行工作流
|
||
success, report = await executor.execute(
|
||
nodes=[...],
|
||
edges=[...],
|
||
global_context={...}
|
||
)
|
||
|
||
# 返回报告结构
|
||
{
|
||
"execution_id": "uuid",
|
||
"total_duration": 0.123,
|
||
"node_infos": {
|
||
"node_id": {
|
||
"status": "success/error",
|
||
"duration": 0.05,
|
||
"cache_hit": False
|
||
}
|
||
},
|
||
"node_results": {
|
||
"node_id": {"outputs": {...}, "context": {...}}
|
||
}
|
||
}
|
||
```
|
||
|
||
### WorkflowPackager
|
||
|
||
```python
|
||
# 验证
|
||
valid, error = WorkflowPackager.validate_function_workflow(nodes, edges)
|
||
|
||
# 打包
|
||
func_def = WorkflowPackager.package_as_function(
|
||
node_id="id",
|
||
nodes=[...],
|
||
edges=[...],
|
||
display_name="显示名",
|
||
description="描述"
|
||
)
|
||
```
|
||
|
||
### DimensionTransformer
|
||
|
||
```python
|
||
mode = DimensionTransformer.infer_dimension_mode(
|
||
source_type=EdgeType.ARRAY,
|
||
target_type=EdgeType.SCALAR,
|
||
target_is_list=False
|
||
)
|
||
# 返回：DimensionMode.EXPAND
|
||
```
|
||
|
||
---
|
||
|
||
## 常用工作流模式
|
||
|
||
### 模式 1：数据处理流水线
|
||
|
||
```
|
||
Input → Filter → Map → Reduce → Output
|
||
```
|
||
|
||
### 模式 2：并行处理
|
||
|
||
```
|
||
Input → ┬→ Process1 ──┬→ Concat → Output
|
||
└→ Process2 ──┘
|
||
```
|
||
|
||
### 模式 3：嵌套函数
|
||
|
||
```
|
||
Input → [Function1 → Function2 → Function3] → Output
|
||
```
|
||
|
||
### 模式 4：条件分支
|
||
|
||
```
|
||
Input → Condition ─┬→ Path1 ──┬→ Output
|
||
└→ Path2 ──┘
|
||
```
|
||
|
||
---
|
||
|
||
## 常见错误和解决方案
|
||
|
||
### ❌ 错误：函数工作流验证失败
|
||
|
||
```
|
||
Error: 函数节点工作流必须包含至少一个InputNode
|
||
```
|
||
|
||
✅ **解决**：确保子工作流包含 InputNode：
|
||
```python
|
||
nodes = [
|
||
{"id": "input", "type": "InputNodeImpl"}, # ← 必须有
|
||
{"id": "logic", "type": "MyNode"},
|
||
{"id": "output", "type": "OutputNodeImpl"} # ← 必须有
|
||
]
|
||
```
|
||
|
||
### ❌ 错误：类型不匹配
|
||
|
||
```
|
||
Error: unsupported operand type(s) for *: 'dict' and 'int'
|
||
```
|
||
|
||
✅ **解决**：检查输入端口名是否正确：
|
||
```python
|
||
# 错误
|
||
{"source": "input", "sourcePort": "output", "target": "map", "targetPort": "values"}
|
||
↑ 错误的端口名
|
||
|
||
# 正确
|
||
{"source": "input", "sourcePort": "values", "target": "map", "targetPort": "values"}
|
||
↑ 使用 global_context 中的字段名
|
||
```
|
||
|
||
### ❌ 错误：无法获取节点
|
||
|
||
```
|
||
Error: 未知的节点类型: MyNode
|
||
```
|
||
|
||
✅ **解决**：确保节点已注册：
|
||
```python
|
||
from app.nodes.advanced_example_nodes import * # ← 导入所有节点
|
||
from app.core.node_registry import NodeRegistry
|
||
|
||
print(NodeRegistry.list_all()) # 查看已注册的节点
|
||
```
|
||
|
||
---
|
||
|
||
## 性能调优建议
|
||
|
||
### 缓存优化
|
||
|
||
```python
|
||
# 启用缓存
|
||
CacheManager.init_memory_cache(max_size=1000, ttl=3600)
|
||
CacheManager.init_disk_cache(Path("cache"))
|
||
|
||
# 查看缓存统计
|
||
stats = CacheManager.get_stats()
|
||
print(f"命中率: {stats['hit_ratio']}%")
|
||
```
|
||
|
||
### 升维优化
|
||
|
||
```python
|
||
# 升维时避免大数组（>10000 元素）
|
||
# 如果必须：考虑使用向量化节点或并行处理
|
||
|
||
# 检查升维次数
|
||
node_info = report["node_infos"]["node_id"]
|
||
expansions = node_info.get("dimension_expansions", 0)
|
||
```
|
||
|
||
### 执行监控
|
||
|
||
```python
|
||
# 查看各节点耗时
|
||
for node_id, info in report["node_infos"].items():
|
||
print(f"{node_id}: {info['duration']}ms")
|
||
|
||
# 找出性能瓶颈
|
||
slow_nodes = [n for n, i in report["node_infos"].items() if i['duration'] > 100]
|
||
```
|
||
|
||
---
|
||
|
||
## 文档导航
|
||
|
||
- 📖 [完整功能文档](./ADVANCED_FEATURES.md)
|
||
- 🏗️ [架构设计文档](./BACKEND_ARCHITECTURE_COMPLETE.md)
|
||
- ✅ [完成报告](./COMPLETION_REPORT.md)
|
||
- 📚 [本文档](./QUICK_REFERENCE.md)
|
||
|
||
---
|
||
|
||
## 版本信息
|
||
|
||
| 项目 | 版本 |
|
||
|------|------|
|
||
| TraceStudio | v2.0 |
|
||
| 高级功能 | Beta |
|
||
| 状态 | ✅ 生产就绪 |
|
||
| 最后更新 | 2025-01-08 |
|
||
|
||
---
|
||
|
||
**需要帮助？** 查看详细文档或运行测试：
|
||
```bash
|
||
python server/tests/test_advanced_features.py
|
||
```
|