99 lines
3.9 KiB
Markdown
99 lines
3.9 KiB
Markdown
|
# TraceStudio
|
|||
|
|
|
|||
|
|
TraceStudio 是一个分布式的、节点式的自动化性能分析平台。它采用 **Master-Worker** 架构，旨在构建通用的性能数据分析与自动化流水线。
|
|||
|
|
|
|||
|
|
## 核心理念 (Core Concepts)
|
|||
|
|
|
|||
|
|
* **分布式架构**:
|
|||
|
|
* **Server (The Hub)**: 负责 API 网关、图解析与任务分发。
|
|||
|
|
* **Client (The Worker)**: 无头（Headless）计算节点，负责算力贡献与自定义逻辑执行。
|
|||
|
|
* **BYOC (Bring Your Own Compute)**: 允许用户接入本地 Client，运行自己定义的私有节点逻辑，实现数据不出域或利用本地特定环境。
|
|||
|
|
* **协议先行 (Protocol First)**: `pytrace` 核心库定义了一切契约（NodeBase, Specs, 序列化），Server 与 Client 必须严格遵守同一套标准。
|
|||
|
|
* **去 UI 化**: 后端不包含 Web 前端代码，仅提供 API 供外部前端调用。
|
|||
|
|
|
|||
|
|
## 架构拓扑 (Architecture)
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
/
|
|||
|
|
├── pytrace/ # [核心共享库] (Python Package)
|
|||
|
|
│ ├── api/ # [面向用户] Node, Decorators, IO
|
|||
|
|
│ ├── runtime/ # [面向系统] Executor, Registry, Context
|
|||
|
|
│ ├── model/ # [面向数据] Specs, Enums, Data
|
|||
|
|
│ ├── internal/ # [面向框架] MetaMap, Constants
|
|||
|
|
│ └── nodes/ # 通用标准节点库
|
|||
|
|
├── server/ # [中心服务器] (The Hub)
|
|||
|
|
│ ├── api/ # HTTP API (FastAPI)
|
|||
|
|
│ └── dispatcher/ # 路由分发器 (基于能力的路由)
|
|||
|
|
├── client/ # [计算节点] (The Headless Worker)
|
|||
|
|
│ └── registry/ # 本地能力注册
|
|||
|
|
└── docs/ # 协议文档
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 核心组件说明
|
|||
|
|
|
|||
|
|
### 1. Pytrace (Shared Library)
|
|||
|
|
系统的“通用语言”。Server 和 Client 必须依赖完全一致的 `pytrace` 版本。
|
|||
|
|
* **TraceNode**: 所有可执行节点的抽象基类。
|
|||
|
|
* **Specs**: 使用 Pydantic 定义的数据模型 (`NodeSpec`, `PortSpec`, `ParamSpec`)，用于生成前端元数据。
|
|||
|
|
|
|||
|
|
### 2. Server (The Hub)
|
|||
|
|
* **能力路由 (Capability-Based Routing)**: 维护一张路由表，记录哪个 Client 拥有哪个自定义 Node。
|
|||
|
|
* **智能缓存**: 基于 `Hash(NodeVersion + InputData + Params)` 进行结果缓存。
|
|||
|
|
|
|||
|
|
### 3. Client (The Worker)
|
|||
|
|
* **握手机制**: 启动时向 Server 汇报自己拥有的节点列表 (Capabilities)。
|
|||
|
|
* **任务执行**: 监听任务 -> 反序列化 (dill) -> 执行 -> 序列化结果 -> 返回。
|
|||
|
|
|
|||
|
|
## 开发指南：定义节点
|
|||
|
|
|
|||
|
|
TraceStudio 使用**装饰器驱动**的方式来定义节点。所有节点需继承自 `pytrace.api.node.TraceNode`。
|
|||
|
|
|
|||
|
|
### 示例代码
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
|
|||
|
|
pip install -e .
|
|||
|
|
|
|||
|
|
from typing import Any
|
|||
|
|
from pytrace.api.node import TraceNode
|
|||
|
|
from pytrace.api.decorators import input_port, output_port, parameter, node_meta
|
|||
|
|
|
|||
|
|
@node_meta(
|
|||
|
|
display_name="Threshold Filter",
|
|||
|
|
icon="filter-icon",
|
|||
|
|
description="Filters data based on a numeric threshold."
|
|||
|
|
)
|
|||
|
|
class ThresholdFilterNode(TraceNode):
|
|||
|
|
|
|||
|
|
# 定义输入端口 (注意: label 字段是必填的，用于 UI 显示)
|
|||
|
|
@input_port(name="data_in", label="Input Data", type="dataframe")
|
|||
|
|
|
|||
|
|
# 定义输出端口
|
|||
|
|
@output_port(name="data_out", label="Filtered Data", type="dataframe")
|
|||
|
|
|
|||
|
|
# 定义可配置参数
|
|||
|
|
@parameter(name="threshold", label="Threshold Value", type="float", default=0.5)
|
|||
|
|
def process(self, io: Any, context: Any) -> None:
|
|||
|
|
"""
|
|||
|
|
节点的执行逻辑。
|
|||
|
|
"""
|
|||
|
|
# 1. 获取输入
|
|||
|
|
# (假设 io 提供了 get_input 方法)
|
|||
|
|
data = io.get_input("data_in")
|
|||
|
|
|
|||
|
|
# 2. 获取参数
|
|||
|
|
thresh = self.params.get("threshold", 0.5)
|
|||
|
|
|
|||
|
|
# 3. 执行业务逻辑
|
|||
|
|
# result = data[data['value'] > thresh]
|
|||
|
|
|
|||
|
|
# 4. 设置输出
|
|||
|
|
# io.set_output("data_out", result)
|
|||
|
|
pass
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 启动服务
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
uvicorn server.app.main:app --reload
|
|||
|
|
```
|