数据可视化机器学习前端后端【免费下载链接】tensorboardTensorFlows Visualization Toolkit项目地址https://gitcode.com/gh_mirrors/te/tensorboard点击查看免费下载本篇技术指南围绕 TensorBoard HParams超参数调优插件的 HTTP API 展开系统讲解其基于 Protocol Buffersproto3的 JSON 编码约定、GET/POST 两种请求方式、三个核心数据端点experiment、session_groups、metric_evals的请求/响应协议以及背后的数据模型与源码实现。读者读完可掌握如何直接通过 HTTP 调用 HParams 后端接口理解 session group 聚合、过滤、排序的底层机制并能基于本仓库源码独立调试或扩展该插件。一、API 总体设计一个 proto3 驱动的 REST 风格接口HParams 插件的后端HParamsPlugin见 hparams_plugin.py对外提供了一组 HTTP 接口用于前端读取超参数实验数据。其设计核心有两点请求与响应都是 Protocol Buffer 消息每个端点end-point都对应一个请求 proto并返回一个响应 proto。一律使用 JSON 编码传输请求体按 proto3 的 JSON 映射规则编码为 JSON 字符串响应同样以 JSON 返回。关于 proto 与 JSON 的映射规则字段名、enum 值、bytes 编码等可参考 proto3 JSON 规范中对json_format的说明。这种设计使接口天然具备类型约束——前端组件如tf-hparams-backend.ts与后端共享api.proto中定义的消息类型前后端通过 api.proto 保持契约一致该文件注释中明确要求如果你修改了任何消息务必同步更新 api.d.ts。GET 与 POST 的请求传递方式同一套端点同时支持 HTTP GET 与 POST 两种调用方式区别仅在于请求的携带位置POST请求 proto 的 JSON 编码放在请求体request body中。GET请求 proto 的 JSON 编码放在名为request的 URL 查询参数中注意需要做 URL 转义。这一逻辑在源码中有精确对应。hparams_plugin.py中的_parse_request_argument()函数按请求方法选择数据来源request_json ( request.data if request.method POST else request.args.get(request) ) try: return json_format.Parse(request_json, proto_class()) except (AttributeError, json_format.ParseError) as e: raise error.HParamsError(...)可以看到后端统一用json_format.Parse()把 JSON 解析成对应的请求 proto如果 JSON 缺失或格式错误会抛出HParamsError最终被包装成 HTTP 400 Bad Request 返回。前端侧tf-hparams-backend.ts 默认使用 GET构造函数useHttpGet true其_sendRequest()方法用JSON.stringify(request_proto)把请求 proto 序列化为 JSON 后拼入request查询参数若useHttpGet为 false 则改用 POST把 JSON 作为text/plain请求体发送。二、端点路由约定1. 统一前缀/data/plugin/hparams按照 TensorBoard 的惯例所有端点都带有data/plugin/hparams前缀。该前缀可以通过 TensorBoard 的路由配置改为其他值即插件挂载路径可定制。HParams 插件实际注册的完整路由如下见hparams_plugin.py的get_plugin_apps()路由处理函数对应请求 proto/data/plugin/hparams/experimentget_experiment_routeGetExperimentRequest/data/plugin/hparams/session_groupslist_session_groups_routeListSessionGroupsRequest/data/plugin/hparams/metric_evalslist_metric_evals_routeListMetricEvalsRequest/data/plugin/hparams/download_datadownload_data_routeListSessionGroupsRequest另需format、columnsVisibility查询参数其中download_data是额外提供的导出端点它复用ListSessionGroupsRequest支持把 session groups 导出为指定格式format参数的数据文件前端 tf-hparams-backend.ts 中的getDownloadUrl()正是为生成该导出链接而设计。2. 关于 experiment name 的说明一个值得注意的设计细节虽然当前单个 TensorBoard UI 窗口只支持展示一个实验experiment但 API 层仍然要求请求中携带实验名experiment_name字段。这是为将来支持多实验预留的扩展点——具体是否尊重该实验名、如何解析它由 API 服务器即插件后端自己决定。在现有实现中实验名通常对应 TensorBoard 的 experiment_id 路由参数hparams_plugin.py中通过plugin_util.experiment_id(request.environ)获取。三、三个核心端点的协议详解1./data/plugin/hparams/experiment返回定义实验元数据的Experiment对象。Args请求 protoGetExperimentRequest定义于 api.proto字段类型说明experiment_namestring必填实验的唯一全局标识include_metricsoptional bool是否在结果中包含指标元数据默认 truehparams_limitoptional int32返回的超参数元数据条数上限为 0 时返回全部ReturnsExperiment消息包含实验名、描述、创建者、创建时间以及超参数元数据列表hparam_infos和指标元数据列表metric_infos。2./data/plugin/hparams/session_groups列出实验中的 session groups会话组。这是最复杂、最核心的端点因为它承载了过滤、排序、聚合与分页四类能力。Args请求 protoListSessionGroupsRequest定义于 api.proto字段类型说明experiment_namestring实验名allowed_statusesrepeated Status只统计状态在集合内的 sessionSTATUS_UNKNOWN/SUCCESS/FAILURE/RUNNINGcol_paramsrepeated ColParams每个元素描述一个列某个超参数或指标的过滤与排序规则aggregation_typeAggregationType组内多 session 的指标聚合方式AVG/MEDIAN/MIN/MAXaggregation_metricMetricName当聚合类型为 MEDIAN/MIN/MAX 时用于选择代表 session的指标start_indexint32返回结果切片slice的起始索引0 基slice_sizeint32返回的 session group 数量include_metricsoptional bool是否包含指标默认 trueReturnsListSessionGroupsResponse含两个字段session_groupsSessionGroup列表本次切片内的total_size完整过滤排序后列表的总大小用于前端分页计算可设为 -1 表示未知。后端实现中切片逻辑为session_groups[start_index : start_index slice_size]即实际返回数量为min(slice_size, total_size - start_index)见 list_session_groups.py。3./data/plugin/hparams/metric_evals返回某个 session 中指定指标的一系列评估值evaluation。Args请求 protoListMetricEvalsRequest定义于 api.proto字段类型说明experiment_namestring实验名session_namestringsession 的名称metric_nameMetricName指标标识group tagReturns一个 JSON 数组其元素是形如[wall_time, step, value]的三元素数组wall_time评估发生的时间UNIX 纪元以来的秒数step评估发生时所在的训练步value指标评估值标量浮点数。为什么用扁平数组而非结构化消息文档中明确指出这是为了与 Scalars 插件所期望的指标评估数据格式保持兼容。源码印证了这一点——list_metric_evals.py 的Handler.run()直接把请求转交给 Scalars 插件run, tag metrics.run_tag_from_session_and_metric( self._request.session_name, self._request.metric_name ) body, _ self._scalars_plugin_instance.scalars_impl( self._request_context, tag, run, self._experiment, scalars_plugin.OutputFormat.JSON, ) return body而hparams_plugin.py的list_metric_evals_route在进入 Handler 之前会先通过_get_scalars_plugin()检查 Scalars 插件是否已加载未加载则返回 404。四、核心数据模型理解 API 的语义基础要正确调用上述 API需要理解 api.proto 中定义的数据模型。它们的层级关系为Experiment实验→ 多个SessionGroup会话组→ 多个Session会话→ 指标评估值。Experimentname实验全局标识description描述可含 Markdownuser归属用户或组的 idtime_created_secs创建时间UNIX 秒hparam_infos实验用到的每个超参数的元信息HParamInfoname、display_name、description、数据类型、值域 domain、differs布尔标记metric_infos实验用到的每个指标的元信息MetricInfoMetricName、display_name、description、DatasetType。其中HParamInfo的值域domain是一个 oneof要么是离散值列表domain_discretegoogle.protobuf.ListValue要么是数值区间domain_intervalInterval闭区间[min_value, max_value]。数据类型DataType有四种DATA_TYPE_UNSET、DATA_TYPE_STRING、DATA_TYPE_BOOL、DATA_TYPE_FLOAT64。SessionGroup 与 SessionSessionGroup一组共享相同超参数取值的 session 集合。当用户为处理非确定性训练而对同一组超参数重复训练多次时这些 session 归入同一组在没有重复实验时每个组恰好只有一个 session。其hparams字段是超参数名 → 值的映射mapstring, google.protobuf.Valuemetric_values是组内聚合后的指标值列表sessions是组内 session 列表另有可选的monitor_url。Session单次训练会话含name实验内唯一、start_time_secs、end_time_secs未结束或不可得时为 0、status、model_uri如 checkpoint 目录、metric_values、monitor_url。Status枚举为STATUS_UNKNOWN/SUCCESS/FAILURE/RUNNING。MetricName用 (group, tag) 二元组标识指标指标不靠单一字符串标识而是MetricName{group, tag}二元组。文档中的设计意图是group通常对应数据集或子目录如 validation / trainingtag对应标量 summary 的 tag如 loss这样 UI 可以把同一计算在不同数据集上的指标放到同一张图里对比。在典型的 TensorFlow 导出设置中session 的指标以 Scalars 插件 summary 的形式写入 runsession_base_log_dir/sub_dir与某个 tag。换算规则见 metrics.py 的run_tag_from_session_and_metric()run os.path.join(session_name, metric_name.group)group 为空时去除结尾斜杠tag metric_name.tag。这也是/metric_evals端点能直接把请求转给 Scalars 插件的前提。五、源码级深度ColParams 如何实现过滤与排序ListSessionGroupsRequest.col_params是 API 中功能最密集的部分见 api.proto每个ColParams描述一列的排序与过滤字段说明metric/hparamoneof该列对应哪个指标或超参数order排序方向ORDER_UNSPECIFIED/ORDER_ASC/ORDER_DESCmissing_values_first缺失值是否排在其他值之前order 未指定时忽略filter_regexp仅对字符串超参数有效正则部分匹配用^regexp$可全匹配filter_interval仅对数值列有效闭区间过滤filter_discrete对所有类型有效显式离散集合exclude_missing_values是否排除值为缺失的 session groupinclude_in_result是否在响应中返回该列请求中未出现于任何 ColParams 的超参数/指标不会出现在结果中排序规则list_session_groups.py的_sort()中体现了精确的排序语义首先按 session group 名排序保证结果确定性然后按col_params中order非ORDER_UNSPECIFIED的子集排序col_params 的先后顺序决定排序键的优先级第一个是主排序键第二个是次级排序键……。实现上通过逆序遍历并多次sort()达成后排序的主键优先级最高文档特别注明session group 名会作为最低优先级的排序键自动追加因此响应顺序永远确定。过滤规则_create_filter()依据filteroneof 构造不同的过滤函数正则re.search部分匹配、闭区间min v max、离散集合Pythonin语义。若列的值为缺失None则是否通过取决于exclude_missing_values。如果完全不指定filter字段且允许缺失值则跳过该过滤器常见情况的性能优化。注意list_session_groups.py源码中的一条安全注释正则过滤器直接使用 Python 的re库可能被构造出指数级耗时的输入在迁移到真正的多租户服务器时需要用更安全的实现替换——这属于实现层面的已知注意点。六、源码级深度SessionGroup 的指标聚合策略当同一 session group 内有多个 session 时aggregation_type决定组级metric_values如何计算见 list_session_groups.py聚合类型组级指标值AGGREGATION_AVG或未指定时的默认值组内各 session 该指标的平均值training_step为平均步数截断取整wall_time_secs为平均值AGGREGATION_MEDIAN取中位 session的指标值——即aggregation_metric取值中位数对应的那个 sessionAGGREGATION_MIN取aggregation_metric取值最小的 session 的指标值AGGREGATION_MAX取aggregation_metric取值最大的 session 的指标值对于 MEDIAN/MIN/MAX源码_measurements()的一个关键细节是中位数/极值只在该指标已在组内最大训练步处被测量的 session 子集内选取MEDIAN 在组内 session 数为偶数时选择较低中间值的 session 作为代表。这些行为都有对应的单元测试覆盖例如 list_session_groups_test.py 中的test_aggregation_median_current_temp、test_aggregation_max_current_temp、test_include_in_result等分别验证了中位数代表选择、极值代表选择以及include_in_result对响应字段裁剪的效果。七、数据写入侧summary 元数据如何与 API 对接HParams 的数据并非由 API 端点直接采集而是由训练程序通过 summary 写入再由 API 端点读取。写入侧的标签常量定义于 metadata.pyEXPERIMENT_TAG _hparams_/experiment实验元数据写入空 runSESSION_START_INFO_TAG _hparams_/session_start_info会话开始信息写入 runsession_nameSESSION_END_INFO_TAG _hparams_/session_end_info会话结束信息状态、结束时间。对应的负载消息定义在 plugin_data.protoHParamsPluginData是一个 oneofexperiment/session_start_info/session_end_info外加version字段。SessionStartInfo携带超参数值映射mapstring, google.protobuf.Value、model_uri、monitor_url、group_name为空则该 session 自成一组、start_time_secsSessionEndInfo携带status与end_time_secs。list_session_groups.Handler.run()的数据来源有两个路径见 list_session_groups.py优先从 summary 标签构建先尝试从EXPERIMENT_TAG与SESSION_START_INFO标签元数据构造 SessionGroup回退到 DataProvider若找不到上述标签则使用DataProvider.read_hyperparameters()的结果构建_session_groups_from_data_provider()。metadata.py中的parse_session_start_info_plugin_data()等函数在解析时还会校验plugin_data.version不匹配则抛HParamsError。八、端到端调用示例综合以上协议给出两个可直接套用的调用示例假设 TensorBoard 运行在本地默认端口 6006。GET 方式获取实验元数据# 请求 proto 的 JSON{experiment_name: my_exp} curl http://localhost:6006/data/plugin/hparams/experiment?request%7B%22experiment_name%22%3A%22my_exp%22%7D响应为Experiment消息的 JSON例如{ name: my_exp, hparamInfos: [ { name: optimizer, type: DATA_TYPE_STRING, domainDiscrete: {values: [adam, sgd]}, differs: true } ], metricInfos: [ { name: {group: validation, tag: loss}, datasetType: DATASET_VALIDATION } ] }注意 proto3 JSON 编码中字段名使用 lowerCamelCase。POST 方式列出 session groups 并按指标过滤排序curl -X POST http://localhost:6006/data/plugin/hparams/session_groups \ -H Content-Type: text/plain \ -d { experiment_name: my_exp, start_index: 0, slice_size: 20, aggregation_type: AGGREGATION_AVG, allowed_statuses: [STATUS_SUCCESS, STATUS_RUNNING], col_params: [ {hparam: optimizer, order: ORDER_ASC, filter_regexp: ^adam$}, {metric: {group: validation, tag: loss}, order: ORDER_ASC} ] }响应ListSessionGroupsResponse的 JSON 形如{ sessionGroups: [ { name: group_1, hparams: {optimizer: {stringValue: adam}}, metricValues: [ {name: {group: validation, tag: loss}, value: 0.31, trainingStep: 100, wallTimeSecs: 1600000000.0} ], sessions: [ {name: session_1, status: STATUS_SUCCESS, startTimeSecs: 1599999000.0} ] } ], totalSize: 42 }GET 方式读取单个 session 的指标评估序列curl http://localhost:6006/data/plugin/hparams/metric_evals?request%7B%22experiment_name%22%3A%22my_exp%22%2C%22session_name%22%3A%22session_1%22%2C%22metric_name%22%3A%7B%22group%22%3A%22validation%22%2C%22tag%22%3A%22loss%22%7D%7D响应为 JSON 数组Scalars 兼容格式[ [1600000000.0, 0, 0.62], [1600000010.0, 10, 0.45], [1600000020.0, 20, 0.31] ]九、结语TensorBoard HParams 插件的 HTTP API 是一个以 proto 为契约、以 JSON 为传输格式的轻量 REST 接口。理解它的关键在于把握三点一是 GET/POST 下请求携带位置的约定二是三个端点各自请求/响应 proto 的字段语义三是ColParams与aggregation_type所承载的过滤、排序、聚合能力。结合本仓库中 api.proto、hparams_plugin.py、list_session_groups.py 与 list_session_groups_test.py 等源码你可以完整追踪从 HTTP 请求到 summary 标签解析、再到 session group 组装与聚合的整条数据链路为二次开发或故障排查打下坚实基础。赞分享数据可视化机器学习前端后端【免费下载链接】tensorboardTensorFlows Visualization Toolkit项目地址https://gitcode.com/gh_mirrors/te/tensorboard点击查看免费下载相关推荐Aptos Indexer GRPC File Store 深度实战指南从 Redis 缓存到云存储的文件化数据落地Aptos Indexer GRPC File Store 深度实战指南从 Redis 缓存到云存储的文件化数据落地 Indexer GRPC File St数据可视化机器学习前端后端OneUptime 权限参考文档深度解析从 Dashboard 到 API 的单源权限目录OneUptime 权限参考文档深度解析从 Dashboard 到 API 的单源权限目录 OneUptime 的权限参考页面 docs/permissio数据可视化机器学习前端后端TensorBoard 客户端—服务器 HTTP API 指南/data 数据接口与插件路由机制详解TensorBoard 客户端—服务器 HTTP API 指南 /data 数据接口与插件路由机制详解 TensorBoard 的前端与后端通过一组约定清晰的数据可视化机器学习前端后端上一篇推荐开源项目Flurl - 现代化的HTTP客户端库下一篇Ultimate Vocal Remover GUI三步轻松分离人声与伴奏的AI神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考