thamos 1.29.1

作为CLI工具使用Thamos

Thamos已发布在PyPI上。请参阅下述安装说明，为您的存储库设置Thoth/Thamos。

# Install Thamos CLI tool:
$ pip3 install thamos  # keep in mind: requires Python 3.6+!!
# Go to repository that should be managed by Thoth which already has Pipfile present:
$ cd ~/git/repo/
# Setup Thamos configuration:
$ thamos config
# Add packages.
$ thamos add tensorflow
# Ask Thoth for software stack recommendations:
$ thamos advise
# Install packages:
$ thamos install  # can be merged using `thamos advise --install`
# Retrieve logs of the last analysis:
$ thamos log

由于Thamos注意到分析ID可提高thamos日志的用户体验，建议将.thoth_last_analysis_id文件添加到.gitignore中。如果已开启虚拟环境管理，添加.venv可能也很有用。

请参阅thoth-station/cli-examples存储库中的示例。

推荐类型

请参阅此文档获取关于Thoth提供的推荐类型详细信息的详细信息。

根据环境变量调整配置

您可以通过使用环境变量扩展条目来调整每次Thamos CLI或Thamos库加载配置文件时的内容。如果您想在运行时（例如在部署中）参数化一些选项，这将很有用。

由于安全原因，此行为默认情况下被明确禁用。但是，您可以通过设置THAMOS_CONFIG_EXPAND_ENV环境变量为1来启用它（显式设置为0将关闭此行为，默认值）

THOTH_HOST=test.thoth-station.ninja THAMOS_CONFIG_EXPAND_ENV=1 thamos advise
2019-03-13 11:22:59,562 [18639] INFO     thamos.config: Expanding configuration file based on environment variables

以下是一个示例，其中要扩展的条目具有大括号内的环境变量

host: {THOTH_HOST}

请注意，扩展是通过直接用环境变量的值替换这些值来完成的，这意味着需要考虑类型（具有值"true"的环境变量将作为true放入配置文件）。

使用自定义配置文件模板

您可以使用自己的自定义配置文件作为模板。如果您想要一些配置条目保持不变，而只扩展一些配置选项，这特别有用。换句话说，您可以对配置文件进行参数化。

配置文件模板的示例可以是

host: {THOTH_SERVICE_HOST}
tls_verify: true
requirements_format: {requirements_format}

runtime_environments:
  - name: '{runtime_environment_name}'
    operating_system:
      name: {os_name}
      version: '{os_version}'
    labels:
      foo: bar
      key: value
    hardware:
      cpu_family: {cpu_family}
      cpu_model: {cpu_model}
      gpu_model: {gpu_model}
    python_version: '{python_version}'
    cuda_version: {cuda_version}
    recommendation_type: stable
    platform: '{platform}'

然后，您需要将此配置文件提供给以下命令

thamos config --template template.yaml

以下列出了自动扩展的配置选项，这些选项通过配置子命令提供（这些选项是可选的，并将根据硬件或软件发现进行调整）

平台对应于sysconfig.get_platform()调用。

这些配置选项是可选的，可以与基于环境变量的调整混合使用（例如，请参见上面关于THOTH_SERVICE_HOST的示例）。请注意，环境变量在thamos config调用时不会扩展，而是在其他子命令发出时（例如thamos advise或其他子命令）扩展。

建议输出的格式可以与Pipenv、原始pip或与pip-tools提供的格式类似（实际上与pip相同，因为这些格式可以互换）。该格式通过requirements_format配置选项进行配置，可用的选项包括

• requirements_format: pipenv 用于与Pipenv兼容的输出

• requirements_format: pip 或 requirements_format: pip-tools 用于与pip或pip-tools兼容的输出

标签

可以针对用户特定需求对请求进行标记。在这种情况下，解析器将包括与请求上提供的标签匹配的管道单元。

例如，可以是一个CI系统，它要求建议并使用标签 requester=ci_foo;team=thoth 标注请求。在这种情况下，解析引擎包括特定于CI系统和指定团队的管道单元（除了默认添加的单元）。标签可以在 .thoth.yaml 配置文件或使用CLI中指定（通过CLI传递的标签具有优先级）

thamos advise --labels requester=ci_foo;team=thoth

有关更多信息，请参阅以下 演示。

支持多个运行环境

Thoth根据您的硬件和软件环境（称为运行环境）进行推荐。您可以指定应针对推荐目标的多于一个运行环境。如果您想调整某些特定于运行环境的配置选项，这可能很合适。例如，将机器学习模型部署到使用CUDA的集群，但您在本地不运行CUDA（在本地快速迭代开发，然后在集群上使用大型数据集进行模型训练）。在这种情况下，您可以在 .thoth.yaml 文件中指定两个配置条目

host: {THOTH_SERVICE_HOST}
tls_verify: true
requirements_format: pipenv

runtime_environments:
  - name: 'cuda'  # <<<
    operating_system:
      name: fedora
      version: '32'
    hardware:
      cpu_family: 6
      cpu_model: 94
      gpu_model: 'GeForce GTX 680'
    python_version: '3.8'
    # <<< HERE
    cuda_version: '10.1'  # <<<
    # <<< HERE
    recommendation_type: stable
    platform: 'linux-x86_64'
    openblas_version: '0.3.13'
    openmpi_version: '4.1'
    cudnn_version: '8'
    mkl_version: '2021.1.1'
    base_image: 'quay.io/thoth-station/s2i-thoth-ubi8-py36-mkl:v0.23.0'

  - name: 'no_cuda'  # <<<
    operating_system:
      name: fedora
      version: '32'
    hardware:
      cpu_family: 6
      cpu_model: 94
      gpu_model: null
    python_version: '3.8'
    # <<< HERE
    cuda_version: null  # <<<
    # <<< HERE
    recommendation_type: stable
    platform: 'linux-x86_64'
    openblas_version: '0.3.13'
    openmpi_version: '4.1'
    cudnn_version: null
    mkl_version: '2021.1.1'
    base_image: 'quay.io/thoth-station/s2i-thoth-ubi8-py36:v0.23.0'

.thoth.yaml 中指定的两个运行环境在 cuda_version 配置和它们的名称上有所不同。

要触发名为 cuda 的运行环境的建议，请发出

thamos advise --runtime-environment cuda

要针对名为 no_coda 的后一个运行环境，您可以发出

thamos advise --runtime-environment no_cuda

此选项也可以通过环境变量使用 THAMOS_RUNTIME_ENVIRONMENT=no_cuda 供应。

如果没有明确提供运行环境，Thamos将采用 runtime_environment 列表中声明的第一个运行环境条目。对于上面的示例，它将默认为 cuda 环境

# defaults to the first one - "cuda"
thamos advise

可以自然地结合使用自动展开的配置选项和配置文件模板来使用多个运行环境。

默认情况下，所有在建议过程中生成的文件都存储在项目根目录中。为了维护针对特定运行环境的多个锁文件，可以在Thamos配置文件中配置“覆盖”目录。

列出可用环境和容器镜像

要列出解算器可以解析依赖关系的可用环境，请发出

thamos environments

每个条目指明操作系统的配置、其版本以及可以在每个运行环境部分中配置的Python解释器版本，这些配置可以在 .thoth.yaml 中的每个运行环境部分中进行。

如果您希望列出可用的、准备好使用的容器镜像

thamos images

每个条目都可以设置为 .thoth.yaml 中相应运行环境部分的 base_image 并用作运行Python应用程序的基础。

覆盖目录

可以使用 .thoth.yaml 文件中的 overlays_dir 配置选项配置携带需求文件的多个目录。此配置在全局范围内配置，所有运行环境都从其中继承路径。

一个示例配置文件声明 overlays_dir

host: {THOTH_SERVICE_HOST}
tls_verify: true
requirements_format: pipenv
overlays_dir: overlays

runtime_environments:
  - name: 'fedora-33'
    operating_system:
      name: fedora
      version: '33'
    python_version: '3.8'

  - name: 'ubi-8'
    operating_system:
      name: rhel
      version: '8'
    python_version: '3.8'

在这种情况下，目录结构应遵循提供的配置

.
├── app.py
├── overlays
│   ├── fedora-33
│   │   ├── Pipfile
│   │   ├── Pipfile.lock
│   │   ├── .env
│   │   └── constraints.txt
│   └── ubi-8
│   │   ├── Pipfile
│   │   ├── Pipfile.lock
│   │   ├── .env
│   │   └── constraints.txt
└── .thoth.yaml

overlays 目录中的每个目录都应遵循 .thoth.yaml 文件中声明的运行环境名称，并携带针对给定运行环境特定的文件。

类似于Pipenv文件，可以用于遵守 pip-tools 的需求文件（requirements.in 和 requirements.txt）。

约束文件（constraints.txt）是可选的。

用户可以选择提供 .env 文件，该文件可以声明在执行 thamos run 时应该传递给进程的环境变量。该 .env 文件以 ENV_NAME=VALUE 的形式在单行中声明每个环境变量。可选地，可以使用哈希符号 (#) 进行注释。文件内容的一个示例：

# This is an example .env file.
FOO=bar
ANOTHER_FOO=another_bar

每个 .env 文件可以针对每个覆盖指定。如果没有使用覆盖目录，则 .env 文件可以放置在顶级项目目录中（存在 .thoth.yaml 的目录）。

安装需求

在调用 thamos advise 后解决锁定文件后，可以使用 thamos install 命令安装应用程序堆栈。如果您希望传递要由 pip 使用的其他选项，可以在 -- 后传递它们。

例如，在需要通过代理隧道安装包的企业网络中安装软件包。

thamos install -- --proxy socks5h://127.0.0.1:8029 --trusted-host pypi.org

建议报告结构

使用 thamos advise --json 命令生成的 JSON 格式建议报告的结构可在 Thoth API 建议端点 中找到，以检索建议结果，以及该端点的相应 模式规范。

在 OpenShift 的 s2i 中使用 Thoth 和 thamos

使用配置模板对于 OpenShift 构建尤其有用，您可以在 s2i 仓库中指定您的模板（省略 Pipfile.lock 以启用如 此存储库 中所示的对 thamos advise 的调用）。

然后，您需要提供以下环境变量

• THAMOS_CONFIG_TEMPLATE - 包含模板路径 - 使用 /tmp/src 前缀指向 s2i 仓库的根（例如，如果 template.yaml 是配置模板并且存储在 Git 仓库的根目录中，则为 /tmp/src/template.yaml）。

• THAMOS_NO_INTERACTIVE - 如果您不想省略交互式 thamos，则设置为 1（适合在集群中自动执行的 s2i 构建）。

• THAMOS_NO_PROGRESSBAR - 设置为 1 以禁用等待来自 Thoth 后端响应时的进度条 - 它可能会在构建期间在 OpenShift 控制台中打印出令人烦恼的冗长输出。

• THAMOS_CONFIG_EXPAND_ENV - 设置为 1 以在生成 .thoth.yaml 文件时启用基于环境变量的扩展 - 由于可能的安全影响，需要明确启用此选项。

• THAMOS_FORCE - 设置为 1 不使用缓存结果，始终强制在 Thoth 侧进行分析（注意此选项可以根据部署配置由 Thoth 操作员忽略）。

• THAMOS_VERBOSE - 设置为 1 以在详细模式下运行 thamos 以显示正在发生的情况（客户端的冗长度）。

• THAMOS_DEBUG - 设置为 1 以在 Thoth 后端侧以调试模式运行分析（建议者、来源检查器等），您可以通过运行 thamos logs 或直接在 Thoth 用户 API 上运行来获取日志；分析 ID 在 OpenShift 的构建过程中打印到控制台（服务器的冗长度）。

• THAMOS_DEV - 设置为 1 以考虑开发依赖项，此标志默认为 0 - 启用开发依赖项后，顾问将需要浏览更大的软件堆栈空间，可能以建议的更差的软件堆栈结束（开发依赖项通常在应用程序部署期间不使用）

• THAMOS_DISABLE_CUDA - 设置为 1 以禁用CUDA检测

• THAMOS_NO_EMOJI - 设置为 1 以禁用UTF-8表情符号（在虚拟终端中很有用）

• THAMOS_NO_USER_STACK - 设置为 1 以禁用发送目录中存在的锁文件 - 此锁文件用作搜索满足用户需求时更好的锁文件的基础

• THAMOS_RETRY_ON_ERROR_COUNT - 如果API服务器响应错误HTTP状态，则执行重试次数（默认为3），通常不需要调整此选项

• THAMOS_RETRY_ON_ERROR_SLEEP - 当发现API服务器出现错误时，休眠时间（请参阅 THAMOS_RETRY_ON_ERROR_COUNT），默认为3秒

• THAMOS_NO_PROGRESSBAR - 禁用进度条可视化，在虚拟终端中很有用

• THAMOS_TIMEOUT - 在此时间（以秒为单位）后，Thamos将停止尝试获取结果

• THAMOS_DISABLE_LAST_ANALYSIS_ID_FILE - 如果您不希望创建一个声明上次分析ID的文件（用于在多个命令之间不记住上次分析ID），请设置为 1

• THAMOS_REQUIREMENTS_FORMAT - 用于管理依赖项的requirements风格 - pip、pip-tools、pipenv 之一，如果未指定，则默认为 pipenv

• THAMOS_TOKEN - 用于对后端进行身份验证请求的令牌

有关如何在集群中将构建绑定到特定节点的说明，请参阅 OpenShift s2i 文档。如果您希望对硬件进行自动硬件发现以在硬件上获取优化堆栈，则需要此功能。

将Thamos作为库使用

from thamos.lib import image_analysis
from thamos.config import config

# Set global context.
# Host to Thoth's User API. API discovery will be done
# transparently and the most appropriate API version will be used.
config.explicit_host = "khemenu.thoth-station.ninja"
# TLS verification when communicating with Thoth API.
config.tls_verify = True

image_analysis(
  image="registry.redhat.com/fedora:29",
  registry_user="fridex",
  registry_password="secret!",
  # TLS verification when communicating with registry.
  verify_tls=True,
  nowait=False
)

禁用TLS相关警告

如果您在不使用TLS的情况下与Thoth的用户API进行通信（您已在 .thoth.yaml 文件中将 tls_verify 配置选项设置为 false），则Thamos CLI和Thamos库会在与API服务器进行每次通信时发出警告。要抑制此警告，请将环境变量 THAMOS_DISABLE_TLS_WARNING 设置为非零值

$ export THAMOS_DISABLE_TLS_WARNING=1
$ thamos advise

从OpenAPI自动生成的客户端

Thamos的大部分代码都是自动生成的。您可以通过运行以下命令来更新Thamos

$ ./swagger-codegen.sh

上述命令将下载并运行针对最新OpenAPI规范 User API 的自动代码生成工具。工具的结果将自动放置在此存储库中的 thamos/swagger_client/ 和 Documentation/ 中。它们包括自动生成的代码以及 有关如何使用代码的文档。Thamos本身提供在 thamos/lib 中简化使用基于此自动生成的代码的例程。