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
|
||
``` |