6.9 KiB
6.9 KiB
🚀 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：简单流水线
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：创建函数节点
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：维度转换
# 升维（数组遍历）
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
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
# 验证
valid, error = WorkflowPackager.validate_function_workflow(nodes, edges)
# 打包
func_def = WorkflowPackager.package_as_function(
node_id="id",
nodes=[...],
edges=[...],
display_name="显示名",
description="描述"
)
DimensionTransformer
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：
nodes = [
{"id": "input", "type": "InputNodeImpl"}, # ← 必须有
{"id": "logic", "type": "MyNode"},
{"id": "output", "type": "OutputNodeImpl"} # ← 必须有
]
❌ 错误：类型不匹配
Error: unsupported operand type(s) for *: 'dict' and 'int'
✅ 解决：检查输入端口名是否正确：
# 错误
{"source": "input", "sourcePort": "output", "target": "map", "targetPort": "values"}
↑ 错误的端口名
# 正确
{"source": "input", "sourcePort": "values", "target": "map", "targetPort": "values"}
↑ 使用 global_context 中的字段名
❌ 错误：无法获取节点
Error: 未知的节点类型: MyNode
✅ 解决：确保节点已注册：
from app.nodes.advanced_example_nodes import * # ← 导入所有节点
from app.core.node_registry import NodeRegistry
print(NodeRegistry.list_all()) # 查看已注册的节点
性能调优建议
缓存优化
# 启用缓存
CacheManager.init_memory_cache(max_size=1000, ttl=3600)
CacheManager.init_disk_cache(Path("cache"))
# 查看缓存统计
stats = CacheManager.get_stats()
print(f"命中率: {stats['hit_ratio']}%")
升维优化
# 升维时避免大数组（>10000 元素）
# 如果必须：考虑使用向量化节点或并行处理
# 检查升维次数
node_info = report["node_infos"]["node_id"]
expansions = node_info.get("dimension_expansions", 0)
执行监控
# 查看各节点耗时
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]
文档导航
版本信息
| 项目 | 版本 |
|---|---|
| TraceStudio | v2.0 |
| 高级功能 | Beta |
| 状态 | ✅ 生产就绪 |
| 最后更新 | 2025-01-08 |
需要帮助？ 查看详细文档或运行测试：
python server/tests/test_advanced_features.py