报告

使用ClearML的报告功能，您可以记录笔记、实验发现或任何您想要的内容。您可以在任何ClearML项目中创建报告。

除了其主要文档外，报告还包含一个描述字段，该字段将出现在报告页面的报告卡片中。报告可以根据其描述进行搜索，因此添加描述可以使以后更容易找到报告。

报告是可编辑的Markdown文档，支持：

• Multi-level headings
• 文本格式化：斜体、粗体和删除线
• Bullet and numbered lists
• 表格
• Code Block
• 文本和图像超链接
• 从您的计算机上传的嵌入式图像
• 嵌入的ClearML任务、模型和app内容

发布报告会锁定它以供将来编辑，因此您可以保留其内容。您还可以分享您的报告，下载PDF副本，或简单地复制MarkDown内容并在您选择的编辑器中重复使用。

通过报告页面访问ClearML报告。

嵌入 ClearML 可视化​

您可以将来自ClearML对象（实验、模型和应用程序）的图表和图像嵌入到您的报告中：标量图和其他图表，以及调试样本，这些可以来自单个对象或对象比较页面。这些可视化会随着对象的更新而实时更新。

添加图形资源：

1. 转到您想要嵌入报告的资源（来自单个对象或对象比较的图表或调试样本）

2. 将鼠标悬停在资源上并点击 。

   

   点击Embed in ClearML report。这将生成用于访问资源的嵌入代码，并将其复制到剪贴板。

   

3. 返回到您的报告页面并粘贴代码片段

   

一旦嵌入到报告中，您可以通过点击返回到资源的原始位置（例如比较页面、实验/模型/应用页面）。

自定义嵌入代码​

您可以自定义嵌入代码，以便在报告中显示更复杂的查询。 标准的嵌入代码格式如下：

<iframe
  src="<web_server>/widgets/?type=sample&objectType=task&objects=<object_id>&xaxis=iter&metrics=<metric_name>&variants=Plot%20as%20an%20image&company=<company/workspace_id>"
  width="100%" height="400"
></iframe>

src 参数由以下组件组成：

• 您的网络服务器的URL（例如 app.clear.ml）
• /widget/ - 提供嵌入数据的端点。
• 您的可视化查询参数（路径和查询由问号?分隔）

查询的格式类似于标准查询字符串：=。多个参数-值对使用&分隔：=&=。

查询字符串通常包括以下参数：

• objectType - 要获取的对象类型。选项为 task 或 model（task 还包括 ClearML 应用实例）。
• objects - 对象ID（即任务或模型ID，取决于指定的ObjectType）。指定多个ID如下： objects=&objects=&objects=。或者，您可以输入一个查询，匹配对象的指定资源将会显示。参见下面的动态查询。
• type - 要获取的资源类型。选项有：
  • plot
  • scalar
  • single (单标量值表)
  • sample (调试样本)
  • parcoords (超参数比较图) - 对于此选项，您还需要指定以下参数：
    • metrics - 唯一的指标/变体ID，格式为 metric_id.variant_id (参见下方的注释)
    • variants - 要包含在图表中的参数 (按以下格式写入 .&.)
    • value_type - 指定要使用的指标值。选项有：
      • min_value
      • max_value
      • value (最后一个值)
• xaxis - 设置图表的x轴单位。选项有：
  • iter - 迭代次数（默认）
  • timestamp - 从开始的时间
  • iso_time - 实际时间
• metrics - 指标名称
• variants - 变体的名称
• company - 工作区ID。适用于ClearML托管服务，用于嵌入来自不同工作区的内容
• light - 添加参数以将可视化切换到浅色主题

动态查询​

您可以通过指定对象条件（例如标签、状态、项目等）而不是特定的任务ID来创建更复杂的查询，使用来自tasks.get_all或models.get_all API调用的参数。

对于这些参数，请使用以下语法：

• key=value 用于非数组字段
• key[]=, 用于数组字段。

用&分隔字段。

示例:​

以下是动态查询的示例。所有示例都使用objectType=task，但也可以使用objectType=model。

• 请求项目中最新实验的特定指标变体的标量图：

  src="/widgets/?objectType=task&xaxis=iter&type=scalar&metrics=&variants=&project=&page_size=1&page=0ℴ_by[]=-last_update
  

  请注意，指定了project参数。为了获取最新的单个实验，添加了page_size=1&page=0ℴ_by[]=-last_update。page_size指定每页返回多少结果，page指定返回哪一页（在这种情况下是第一页）——这样你可以指定图表中需要多少实验。order_by[]=-last_update按更新时间降序排列结果（最近的优先）。

• 请求特定标签实验的特定指标变体的标量图：

  src="/widgets/?objectType=task&xaxis=iter&type=scalar&metrics=&variants=&tags[]=__$or,
  

  在tags参数中指定了实验应包含的标签列表。您还可以指定排除实验的标签。请参阅此处的标签过滤器语法示例。

• 请求显示5个实验中准确率最高的training/accuracy标量图（请参阅下方的指标/变体ID说明）：

  src="/widgets/?objectType=task&xaxis=iter&type=scalar&metrics=training&variants=accuracy&project=4043a1657f374e9298649c6ba72ad233&page_size=5&page=0ℴ_by[]=-last_metrics...value"
  

报告页面​

使用报告页面在报告之间导航和管理报告。

您可以在项目视图 或列表视图 中查看报告页面。在列表视图中，所有报告并排显示。在项目视图中，报告根据其项目进行组织，并显示顶级项目。点击项目卡片以查看项目的报告。

项目卡片​

在项目视图中，项目卡片显示项目的摘要报告信息：

点击项目卡片以查看其报告。

报告卡​

在列表视图中，报告卡显示汇总的报告信息：

• Report Name
• Reported Items
• 创建用户
• 最后更新时间
• Status
• Description
• 标签

报告操作​

点击报告卡右上角的以打开其上下文菜单并访问报告操作：

• 重命名 - 更改报告的名称
• 分享 - 复制URL以分享报告
• 添加标签 - 向报告添加标签，以帮助轻松分类报告组。
• 移动到 - 将报告移动到另一个项目中。如果目标项目不存在，则会即时创建。
• 归档 - 将报告从活动报告页面移动到归档
• 删除 - 删除报告。要删除报告，必须先将其存档。

创建报告​

要创建报告，请点击页面右上角的+ 新建报告按钮， 这将打开一个新建报告模态框。

MarkDown 格式化快速指南​

以下是可以在ClearML报告中使用的MarkDown语法的快速参考。

标题级别​

要创建标题，请在您想要转换为标题的短语前添加#。#符号的数量对应于标题级别（即#表示一级标题，##表示二级标题，依此类推）：

MarkDown	Rendered Output
# H1 ## H2 ### H3 #### H4 ##### H5 ###### H6

文本强调​

下表展示了文本格式选项：

引用​

要创建块引用，请在每行引用前添加一个>。通过在嵌套块引用的每行前添加额外的>符号来嵌套块引用。

MarkDown	Rendered Output
> Blockquote >> Nested quote 1 >>> Nested quote 2

列表​

有序列表​

通过用数字后跟句点来编号列表项来创建有序列表。列表项不必正确编号，但列表将从1.开始按数字呈现。

MarkDown	Rendered Output
1. Item 1 2. Item 2 1. Item 3 1. Item 4

无序列表​

通过每行以+、-或*符号开头来创建一个无序列表。可以在同一个列表中使用不同的符号来创建项目符号，但它们都会统一渲染。

你也可以使用勾选框（* [x]），跟在任何项目符号后面。

要嵌套列表，请将嵌套项缩进比其父列表项多2个空格。

MarkDown	Rendered Output
+ Item 1 + Item 2   - Sub-item a:     * Sub-sub-item x     + Sub-sub-item y     - Sub-sub-item z * [x] A checkmark

表格​

MarkDown代码的表格看起来像这样：

|          | Align Right | Align Left | Align Center |
| -------- | -----------:|:---------- |:------------:|
| 1        |           1 | 1          |      1       |
| 11       |          11 | 11         |      11      |

渲染后的输出应该看起来像这样：

在第一行添加表格列名；每个名称前后都有一个管道符号（|）。 在第二行，为每列添加至少三个连字符（---），并在每组连字符前后添加一个管道符号。 在第二行，您可以指定每列内容的对齐方式。要将内容左对齐，请在连字符的左侧放置一个冒号（:）。要右对齐，请在连字符的右侧放置一个冒号。要居中对齐，请在连字符的两侧都放置冒号。

代码​

要渲染内联代码，请用单反引号（`）包围代码。例如 `code` 将被渲染为 code。

要创建块代码，请使用以下选项之一：

• 缩进代码

      from clearml import Task
  
      t = Task.init(project_name='My project', task_name='Base')
  

• 用“围栏”包围代码——三个反引号 (```):

  ```  
  from clearml import Task
  
  t = Task.init(project_name='My project', task_name='Base')  
  ```
  

这两个选项都将呈现为：

from clearml import Task

t = Task.init(project_name='My project', task_name='Base')

语法高亮​

要显示语法高亮，请在第一个围栏后指定编码语言（例如 ```python, ```json, ```js, 等等）：

```python
from clearml import Task

t = Task.init(project_name='My project', task_name='Base')
```

渲染后的输出应该看起来像这样：

from clearml import Task

t = Task.init(project_name='My project', task_name='Base')

链接​

要创建链接，请将链接文本放在括号内，后面跟着用括号括起来的URL链接：

[link text](https://clear.ml)

渲染后的输出应该看起来像这样： link text

要为链接添加标题，当悬停在链接上时可以在工具提示中看到，请在URL链接后的括号内添加标题：

[link with title](https://clear.ml "ClearML Documentation")

渲染的输出应该看起来像这样：带有标题的链接。将鼠标悬停在链接上以查看链接的标题。

可折叠部分​

可折叠面板的MarkDown代码如下所示：

<details><summary>Section title</summary>Collapsible Section Contents</details>

可折叠面板由

它呈现如下：

水平规则​

使用三个连字符（---）、下划线（___）或星号（***）创建水平线：

MarkDown	Rendered Output
--- ___ ***

图片​

要添加图像，请添加一个感叹号，后跟用括号括起来的替代文本，再后跟用括号括起来的图像链接：

![Logo](https://raw.githubusercontent.com/allegroai/clearml/master/docs/clearml-logo.svg)

渲染后的输出应该看起来像这样：

要为图像添加标题，当悬停在图像上时可以在工具提示中看到，请在图像的链接后添加标题：

![With title](https://raw.githubusercontent.com/allegroai/clearml/master/docs/clearml-logo.svg "ClearML logo")

渲染后的输出应该看起来像这样：

将鼠标悬停在图像上以查看其标题。