入门指南#

设置和先决条件#

硬件要求#

  • 最低 GPU 内存 (GB)：对于生成 512^3 或更大尺寸的图像，需要 60 GB。请参考所需的 GPU 内存了解更多详情。

  • CPU x86-64 >= 8 核（推荐）

  • 内存 >= 32 GB（推荐）

  • 最低存储空间：50 GB（28 GB 容器大小）

软件要求#

NGC (NVIDIA GPU Cloud) 账户设置#

  1. 在 NGC 上创建账户

  2. 生成 API 密钥

  3. 设置 NGC_API_KEY

    export NGC_API_KEY=<Your NGC API Key>

  4. 使用您的 NGC API 密钥登录 Docker，命令为 docker login nvcr.io --username='$oauthtoken' --password=$NGC_API_KEY

NGC CLI 工具设置#

  1. 为您的操作系统下载 NGC CLI 工具。

  2. 在本地设置您的 NGC CLI 工具（您需要您的 API 密钥！）

    ngc config set

输入 API 密钥后，您可能会看到组织和团队的多个选项。根据需要选择或按 Enter 键接受默认值。

使用说明#

运行 NIM#

  1. 拉取 NIM 容器

    docker pull nvcr.io/nim/nvidia/maisi:1.0.0

  2. 运行 NIM 容器

    docker run --rm -it --name maisi \
   --runtime=nvidia -e CUDA_VISIBLE_DEVICES=0 \
   -p 8000:8000 \
   -e NGC_API_KEY=$NGC_API_KEY \
   nvcr.io/nim/nvidia/maisi:1.0.0

  3. 使用 docker logs 监控进度

    docker logs --follow maisi

健康和活跃度检查#

  • 就绪检查

    curl localhost:8000/v1/health/ready

  • 活跃度检查

    curl localhost:8000/v1/health/live

  • 等待健康检查返回状态代码 200

    Bash

    base_url="https://127.0.0.1:8000"
endpoint="/v1/health/ready"

response=$(curl -s -o /dev/null -w "%{http_code}" "$base_url$endpoint")

while [ "$response" -ne 200 ]; do
   echo "Waiting for the service to be ready..."
   sleep 5
   response=$(curl -s -o /dev/null -w "%{http_code}" "$base_url$endpoint")
done

echo "Service is ready!"

    Python

    import requests
import time

base_url = "https://127.0.0.1:8000"
response = requests.get(f"{base_url}/v1/health/ready")

while response.status_code != 200:
   response = requests.get(f"{base_url}/v1/health/ready")
   
   time.sleep(5)
print(response.json())

与 API 交互#

MAISI API 提供两个主要端点

  1. /v1/maisi/info：GET 请求以检索服务信息

  2. /v1/maisi/run：POST 请求以生成合成图像

这是一个 Python 脚本，演示如何使用 MAISI NIM API 查询服务信息

import requests
import json

base_url = "https://127.0.0.1:8000"

# Query service info
info_response = requests.get(f"{base_url}/v1/maisi/info")
print("Service Info:", json.dumps(info_response.json(), indent=2))

这是一个生成合成图像的脚本，此脚本将 POST 请求发送到 /v1/maisi/run 并带有图像生成参数。然后它处理响应，保存 ZIP 文件或根据需要显示 JSON 消息。

import requests
from datetime import datetime

base_url = "https://127.0.0.1:8000"

# Generate synthetic image
payload = {
    "num_output_samples": 1,
    "body_region": ["abdomen"],
    "anatomy_list": ["liver", "spleen"],
    "output_size": [512, 512, 512],
    "spacing": [1.0, 1.0, 1.0],
    "image_output_ext": ".nii.gz",
    "label_output_ext": ".nii.gz",
}

generation_response = requests.post(f"{base_url}/v1/maisi/run", json=payload)

if generation_response.status_code == 200:
    print("Files generated successfully!")

    if generation_response.headers.get('Content-Type') == 'application/zip':
        # Save ZIP file with timestamp
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        zip_filename = f"output_{timestamp}.zip"
        with open(zip_filename, "wb") as f:
            f.write(generation_response.content)
        print(f"Output saved as {zip_filename}")

    elif 'application/json' in generation_response.headers.get('Content-Type', ''):
        response_json = generation_response.json()
        print("Response:", response_json.get('message') or response_json.get('error'))

    else:
        print("Unexpected response format")
else:
    print(f"Error {generation_response.status_code}: {generation_response.text}")

注意：当使用 NVIDIA A100 GPU 时，生成单个 512x512x512 图像可能需要大约 10 到 20 分钟。确切时间可能因系统具体配置而异。

停止容器#

要停止容器，请运行

docker stop maisi

可视化输出#

示例输出#

MAISI result

使用 3D Slicer 可视化#

用户可以使用 3D Slicer 的查看器可视化 MAISI NIM 生成的分割结果。我们展示了安装 3D Slicer 和可视化 MAISI 分割的一些入门步骤。

安装 3D Slicer#

要安装 3D Slicer，您需要下载并安装稳定版和预览版。有关安装 3D Slicer 的更多信息，请参阅 3D Slicer 文档。

  • 解压压缩文件，然后在文件系统中双击“3D Slicer”应用程序，根据不同的操作系统选择正确的版本。

可视化和渲染#

  • 打开 3D Slicer 应用程序，在启动面板查看器下

  • 3D Slicer Rendering Example 1

  • 3D Slicer Rendering Example 2

  • 打开 MAISI NIM 生成的 CT 体数据和分割文件，可以是 NRRD 或 NIFTI 文件。拖动文件或从菜单导入。在弹出窗口中，如果您只想加载文件，请选择“体数据”选项。或者您可以选择“分割”模式。

  • 这是生成的 CT 体数据的示例

  • 3D Slicer Rendering Example 2

  • 可视化生成的标签，显示所有标签。

  • 3D Slicer Rendering Example 4

  • 同时可视化 CT 图像及其 MAISI 标签渲染。上图显示了叠加效果。

FAQ（常见问题解答）#

  1. 问：什么是 MAISI，它可以用来做什么？
    答：MAISI（Medical AI for Synthetic Imaging，医学人工智能合成影像）是一种用于生成合成 CT 图像的 3D 潜在扩散模型。它主要用于医学影像研究中的数据增强，帮助补充有限的数据集并提高其他医学人工智能模型的性能。

  2. 问：MAISI 可以用于临床目的吗？
    答：不可以，MAISI 仅用于研究目的，不应用于临床诊断或治疗计划。

  3. 问：运行 MAISI 的最低硬件要求是什么？
    答：MAISI 需要至少 60 GB 内存的 GPU 才能生成 512^3 尺寸的图像。它已在 A100 80GB 和 H100 GPU 上验证。

  4. 问：如何指定我想要在生成的图像中的解剖结构？
    答：您可以使用 API 有效负载中的 anatomy_list 参数来指定所需的解剖结构。有关可用选项的完整列表，请参阅 API 参考部分中的“支持的解剖结构”表。

  5. 问：我可以控制生成的图像中特定器官的大小吗？
    答：是的，您可以使用 controllable_anatomy_size 参数来调整最多 10 个特定器官的大小。大小可以设置为 0.0 到 1.0 之间，或 -1 以移除器官。

  6. 问：MAISI 支持哪些输出格式？
    答：MAISI 可以输出 NIfTI、DICOM 和 Nrrd 格式的图像。您可以使用 image_output_ext 和 label_output_ext 参数指定所需的格式。

  7. 问：在单个 API 调用中，我可以生成多少张图像？
    答：您可以使用 num_output_samples 参数指定要生成的图像数量。没有固定的限制，但生成大量图像可能需要更多时间和资源。

  8. 问：是否可以生成不同身体区域的图像？
    答：是的，您可以使用 body_region 参数指定一个或多个身体区域。可用选项包括“head”、“chest”、“thorax”、“abdomen”、“pelvis”和“lower”。

  9. 问：为什么我只得到部分身体区域？
    答：如果请求的视野 (FOV) 小于实际身体大小，则可能会发生此问题。确保正确设置 output_size 和 spacing 参数以覆盖整个身体区域。这里您可以找到一些推荐的 output_size 和 spacing 值。

  10. 问：为什么我会在请求的身体区域之外获得额外的身体区域？
    答：如果指定的视野 (FOV) 大于请求的身体区域的实际大小，则可能会发生此问题。确保准确设置 output_size 和 spacing 参数，仅覆盖所需的身体区域。这里您可以找到一些推荐的 output_size 和 spacing 值。

  11. 问：在生成图像时，如何处理 API 响应？
    答：API 响应要么是包含生成图像的 ZIP 文件（如果成功），要么是 JSON 消息（如果存在错误或其他信息）。“与 API 交互”部分中提供的 Python 脚本演示了如何处理这两种类型的响应。

  12. 问：如何报告与 MAISI 相关的问题或安全漏洞？
    答：您可以通过 NVIDIA AI Concerns 门户报告安全漏洞或其他问题，网址为 https://www.nvidia.com/en-us/support/submit-security-vulnerability/。

  13. 问：如果 Docker 容器无法启动，我该怎么办？
    答：确保您已安装正确的 NVIDIA 驱动程序（最低版本 535）并且 NVIDIA Container Toolkit 已正确设置。此外，请验证您的系统是否满足最低硬件要求，尤其是 GPU 内存。

  14. 问：如果健康检查失败怎么办？
    答：再等几秒钟，然后重试。如果问题仍然存在，请使用 docker logs --follow maisi 检查 docker 日志以查找任何错误消息。确保您的系统资源没有受到限制，并且容器可以完全访问 GPU。

  15. 问：图像生成期间“内存不足”错误的原因是什么？
    答：确保您的 GPU 至少有 60GB 内存。如果没有，请尝试减小 output_size 参数或一次生成较少的样本。您也可以尝试减少 anatomy_list 中的解剖结构数量。

  16. 问：如何查看生成的输出文件？
    答：输出文件采用 NIfTI、DICOM 或 Nrrd 格式，具体取决于您的指定。您可以使用医学影像软件（如 3D Slicer、ITK-SNAP 或 MRIcroGL）查看这些文件。确保输出文件已在 API 调用中指定的预期位置创建。

  17. 问：如果 NGC CLI 工具设置失败，我该怎么办？
    答：仔细检查您是否输入了正确的 API 密钥。如果问题仍然存在，请尝试从 NGC 网站重新生成新的 API 密钥。此外，请确保您已安装最新版本的 NGC CLI 工具。

  18. 问：我可以调整大型或复杂图像的生成超时时间吗？
    答：是的，您可以在启动 Docker 容器时使用 GENERATE_IMAGE_TIMEOUT 环境变量为图像生成设置自定义超时时间。默认值为 1800 秒（30 分钟）。

  19. 问：是否可以使用不同的端口作为 API 服务器？
    答：是的，您可以在启动 Docker 容器时使用 NIM_HTTP_API_PORT 环境变量指定不同的 API 服务器端口。默认端口为 8000。

如果您遇到任何其他问题，请参阅 NVIDIA MAISI 文档或联系 NVIDIA 寻求支持。

在本页中