Granta MI脚本工具包：批量数据管理与自动化导入实战

如果你做材料数据管理、CAE 仿真支持，或者需要在 Granta MI 里批量维护上千条、上万条试验记录，那么 Scripting Toolkit 是一个绕不开的工具。

Granta MI 是 ANSYS 旗下的材料信息管理系统，核心能力是存储、查询、审批和发布材料数据。Web 界面适合人工查数据和做质量审核，但一旦涉及重复性工作——批量录入新试验、批量修改属性、定期导出数据给下游仿真工具——手动点击就不现实了。Scripting Toolkit 是官方提供的脚本接口，支持 Python 与 .NET（C#），让你用代码连接 MI 服务，完成记录检索、属性读取、记录创建与修改、数据导出等操作。

这篇文章按“先跑通、再深入”的顺序写。我们会先说明这个工具的能力边界和前置条件，然后完成安装、连接、查询、读取、写入、批量导入这一整条链路，最后给出常见报错排查和工程化建议。

适合的读者有三类：材料工程师，想把试验数据从 Excel 批量导入 Granta MI；仿真工程师，要从 MI 取材料属性给 CAE 边界条件；做二次开发的工程师，要把 MI 接入企业数据平台或自动化流程。

1. Granta MI Scripting Toolkit 核心能力速览

从表里可以看出来，这个工具和常见的 AI 推理工具不一样：它不吃显存、不依赖 CUDA，性能瓶颈在网络和 Granta MI 服务端。入门门槛主要是三件事：有可用的 Granta MI 服务实例、有访问权限、会用 Python 的基本操作。

2. 适用场景与使用边界

2.1 适合谁

第一个典型场景是试验数据批量入库。试验室每天产生大量拉伸、冲击、疲劳测试数据，手抄到 MI 界面里效率低且容易错。用 Scripting Toolkit 写一个 CSV 导入脚本，可以把“读取 Excel → 创建记录 → 写入属性 → 提交”的流程自动化。

第二个场景是数据导出与集成。仿真工程师在做 ANSYS Workbench 或其他 CAE 分析时，需要从 MI 取材料属性。用脚本按牌号、批次、规范号查询，再把结果导出为 JSON 或 Excel，可以直接喂给后处理脚本。

第三个场景是数据治理与审计。定期检查数据库里有没有空值、重复记录、异常属性，生成质量报告。这类任务人工做容易漏，脚本做起来很稳定。

2.2 不适合什么

Scripting Toolkit 不是万能入口。Granta MI 的审批流、权限配置、数据库管理这类管理员操作，通常仍然要在 Web 界面或管理控制台完成。脚本接口能读写的是业务数据层，不能替代管理员的后台操作。

另外，它不适合做高并发在线查询。它定位是工程自动化脚本，不是给终端用户用的高并发 Web 服务。如果要做大规模在线查询，应该基于 MI 的官方服务接口重新设计架构，而不是直接让脚本扛请求。

2.3 合规与安全边界

Granta MI 是商业软件，需要合法授权。使用 Scripting Toolkit 前，确认你所在的单位已经采购并部署了对应版本，你拥有相应的访问权限。材料数据往往涉及企业核心知识资产，写入、修改、导出前必须遵守单位的数据管理规范和保密要求。

不要用脚本绕过审批流程、越权读取其他部门的数据，或者把数据库内容导出到非授权环境。做批量修改前，要在测试库或训练库上完整验证。

3. 环境准备与前置条件

3.1 你需要哪些前置条件

在写代码之前，先把下面这些信息从管理员那里确认清楚：

3.2 客户端环境

客户端不需要高配机器，重点是 Python 环境干净。

• 操作系统：Windows 10/11、Linux、macOS 都可能支持，具体以官方要求为准
• Python 版本：不同版本的 Toolkit 对 Python 版本要求不同，一般为 Python 3.8 及以上，安装前看官方文档
• 网络：能解析并访问 MI 服务域名或 IP
• 磁盘：几十 MB 就够，因为 Toolkit 本体很小
• 不需要 GPU

建议用一个独立的 Python 虚拟环境来装，避免和已有项目依赖冲突。

bash复制# 创建虚拟环境（Windows 示例）
python -m venv mi-toolkit-env
mi-toolkit-env\Scripts\activate

# Linux / macOS 示例
# python -m venv mi-toolkit-env
# source mi-toolkit-env/bin/activate

3.3 安装验证

安装后要确认包能正常导入。经典的 Scripting Toolkit Python 导入方式如下：

python复制from GRANTA_MIScriptingToolkit import granta as mpy

# 如果这行能执行，说明环境基本可用
print("Scripting Toolkit import OK")

如果你使用的是新版的 Granta Python SDK，包名和导入路径可能不同，请以官方文档为准。两种包的 API 风格有差异，混用会直接报错。这也是刚上手时最容易踩的坑。

4. 安装部署与连接启动

4.1 用 pip 安装

Scripting Toolkit 的 Python 包通过 pip 安装。包名按你的 Granta MI 版本到官方文档或 PyPI 确认，下面是一个通用安装示例：

bash复制# 先升级 pip，避免老版本安装器出问题
python -m pip install --upgrade pip

# 安装 Scripting Toolkit，包名以官方文档为准
pip install Granta-MI-Scripting-Toolkit

# 如果使用新版 SDK，包名通常为 granta-mi
# pip install granta-mi

安装完成后可以用 pip show 验证：

bash复制pip show Granta-MI-Scripting-Toolkit

如果看到版本信息，说明包已安装。如果报错 No matching distribution found，大概率是包名写错了，或者当前 Python 版本不在该包的支持范围内。

4.2 连接服务的两种方式

连接 Granta MI 服务常见两种认证方式。

第一种是 Windows 集成认证，适合客户端和 MI 服务都在同一域内的情况，脚本里设置 autologon=True。

第二种是用户名密码认证，适合服务端部署在非 Windows 域环境，或者脚本跑在 Linux 服务器上的场景。密码建议通过环境变量传入，不要写死在代码里。

bash复制# 把连接信息放到环境变量，而不是写死在代码里
export MI_SERVER_URL="https://mi-server.example.com/mi/your-instance"
export MI_USERNAME="your-username"

4.3 第一个连接脚本

基础的连接和数据库浏览脚本如下：

python复制from GRANTA_MIScriptingToolkit import granta as mpy
import os

# 方式一：自动登录（Windows 集成认证）
mi = mpy.Connection(
    url="https://mi-server.example.com/mi/your-instance",
    autologon=True,
)

# 方式二：用户名密码登录（从环境变量读取）
# mi = mpy.Connection(
#     url=os.environ["MI_SERVER_URL"],
#     username=os.environ["MI_USERNAME"],
#     password=os.environ["MI_PASSWORD"],
# )

# 获取数据库列表，验证连接是否成功
databases = mi.get_db_list()
for db in databases:
    print(db)

这里需要注意：不同版本的 Connection 类参数名不完全一致，有的版本接受 url，有的版本接受服务管理地址。以你实际安装版本文档为准。只要连接成功并打印出数据库列表，说明服务地址、网络和认证都没问题。

5. 功能测试与效果验证

这个阶段建议按“连接 → 查询 → 读取 → 写入 → 导出”的顺序，逐项验证。

5.1 连接测试：列出数据库

测试目的：确认服务地址、认证、权限都正常。

python复制from GRANTA_MIScriptingToolkit import granta as mpy

mi = mpy.Connection(
    url="https://mi-server.example.com/mi/your-instance",
    autologon=True,
)

dbs = mi.get_db_list()
for db in dbs:
    print("Database:", db)

预期结果：打印出你有权限访问的数据库列表，至少包含一个可用数据库。

判断标准：能打印数据库列表，说明网络链路和认证已通过。如果这一步报错，直接跳到第八节排查。

5.2 查询测试：按条件搜索记录

测试目的：验证能否按属性条件检索记录。

python复制db = mi.get_db("MI Training")
table = db.get_table("Tensile Sample Data")

# 按材料牌号模糊查询
records = table.search_for_records_where("Material Designation", contains="Steel")

print("Found records:", len(records))
for rec in records:
    print(rec.name)

预期结果：返回一批匹配的记录，每条记录有一个唯一名称。

判断标准：查询结果数量与你在 Web 界面看到的筛选结果一致。

常见失败：属性名写错、数据库名写错、表名写错。属性名要和 MI 界面里显示的名称完全一致，包括大小写和空格。

5.3 读取测试：读取属性值

测试目的：验证能否从记录中读取属性数据，包括数值、文本和单位。

python复制records = table.search_for_records_where("Material Designation", contains="Steel")

if records:
    rec = records[0]
    print("Record:", rec.name)

    for attr_name, attr in rec.attributes.items():
        # 不同属性类型的 value 形式不同，串行属性和离散属性需要区分处理
        print(attr_name, "->", attr.value)

预期结果：能打印出该记录的属性名和属性值，数值型属性通常带单位信息。

判断标准：读取结果与 Web 界面里看到的记录内容一致。

常见失败：如果属性值很大（比如一整条应力-应变曲线），直接打印会刷屏，建议先只打印属性名，再定向读取个别属性。

5.4 写入测试：创建记录、更新属性

测试目的：验证脚本能否创建新记录并写入属性值。这一步务必在测试库或训练库上进行。

python复制table = db.get_table("Tensile Sample Data")

# 创建一条新记录
new_rec = table.create_record("SP-2024-0001")
new_rec.attributes["Material Designation"].value = "Steel 42CrMo"
new_rec.attributes["Specimen ID"].value = "MTS-1024"

# 提交到服务端
mi.update([new_rec])
print("Record created:", new_rec.name)

预期结果：脚本正常结束，在 Web 界面能看到新建的记录，属性值正确显示。

判断标准：刷新 MI 界面，记录存在且属性值正确。

常见失败：

• 账号只有只读权限，提交时被拒绝
• 必填属性没有写全，服务端校验失败
• 属性类型不匹配，比如给连续数值属性赋了非法文本

5.5 导出测试：批量导出数据

测试目的：验证能否把查询结果导出为结构化文件，供下游使用。

python复制import json

records = table.search_for_records_where("Material Designation", contains="Steel")

result = []
for rec in records:
    row = {"name": rec.name}
    for attr_name, attr in rec.attributes.items():
        try:
            row[attr_name] = attr.value
        except Exception:
            row[attr_name] = None
    result.append(row)

with open("steel_export.json", "w", encoding="utf-8") as f:
    json.dump(result, f, ensure_ascii=False, indent=2)

print("Exported", len(result), "records")

预期结果：生成本地 JSON 文件，内容与查询结果一致。

判断标准：文件可以被 Python 或其他程序正常读取，数据无乱码、无丢失。

6. 接口 API 与批量任务

6.1 脚本接口的基本调用模式

Scripting Toolkit 的基本调用模式是固定的，理解这个模式就理解了大半 API：

1. 连接服务：创建 Connection 对象
2. 定位表：get_db() 得到数据库，get_table() 得到表
3. 定位记录：搜索或创建记录
4. 操作属性：读取 attributes 字典，或给属性赋新值
5. 提交：调用更新方法把改动同步到服务端

整个模式非常像操作数据库的 ORM。把每一步封装成函数，后续写批量脚本会轻松很多。

6.2 批量导入 CSV 实例

下面是一个从 CSV 批量导入材料数据的完整示例。它包含三个关键设计：先检查记录是否已存在，避免重复导入；分批提交，避免一次性提交过多数据；打印进度日志，方便排查卡住的位置。

python复制import csv
from GRANTA_MIScriptingToolkit import granta as mpy

mi = mpy.Connection(
    url="https://mi-server.example.com/mi/your-instance",
    autologon=True,
)

db = mi.get_db("MI Training")
table = db.get_table("Tensile Sample Data")

CSV_FILE = "tensile_batch.csv"
BATCH_SIZE = 20  # 每 20 条提交一次

records_to_submit = []
total_count = 0

with open(CSV_FILE, "r", encoding="utf-8") as f:
    reader = csv.DictReader(f)

    for row in reader:
        spec_id = row["spec_id"]

        # 幂等检查：已存在则跳过，避免重复创建
        existing = table.search_for_records_where("Specimen ID", equals=spec_id)
        if existing:
            print(f"skip existing: {spec_id}")
            continue

        rec = table.create_record(spec_id)
        rec.attributes["Material Designation"].value = row["material"]
        rec.attributes["Tensile Modulus"].value = row["tensile_modulus"]
        rec.attributes["Tensile Strength"].value = row["tensile_strength"]
        rec.attributes["Test Temperature"].value = row["test_temperature"]
        records_to_submit.append(rec)

        if len(records_to_submit) >= BATCH_SIZE:
            mi.update(records_to_submit)
            total_count += len(records_to_submit)
            print(f"submitted {total_count} records")
            records_to_submit = []

# 提交剩余不足一批的记录
if records_to_submit:
    mi.update(records_to_submit)
    total_count += len(records_to_submit)

print("batch import finished, total:", total_count)

把这个脚本跑一遍，你会直观感受到 Scripting Toolkit 的批量能力。一次提交几十条记录和一条一条提交相比，整体耗时差距很大。

6.3 批量任务的稳定性设计

批量任务不能只写主流程，还要考虑失败恢复。

第一，写操作前先做幂等检查。通过唯一标识（比如试验编号）查询是否已存在，存在就跳过。这样脚本中断后重跑不会产生重复数据。

第二，分批提交。不要攒一万条记录一次性提交。MI 服务端对单次请求的数据量有限制，分批还能让你在日志里看到进度。

第三，加日志。每处理一批记录输出进度信息，出问题时能快速定位到是哪一批、哪条记录。

第四，失败重试要谨慎。如果某条记录属性类型不合法，重试一百次结果都一样。建议先捕获异常，记录失败行，跳过继续跑，最后统一看失败清单。

python复制# 简单失败隔离示例
try:
    mi.update(records_to_submit)
except Exception as e:
    print(f"batch failed at record {spec_id}: {e}")
    failed_specs.extend([r.name for r in records_to_submit])

写完主流程后，把失败清单写到单独的文件里，方便人工复核。

7. 资源占用与性能观察

7.1 客户端资源占用

Scripting Toolkit 客户端本身非常轻量。一个连接和查询脚本，内存占用通常在几十 MB 到几百 MB 之间，取决于你一次性加载了多少属性数据。CPU 占用也不高，除非你要在客户端做复杂的数据清洗和计算。

真正影响性能的是三个地方：网络延迟、MI 服务端的查询能力、单次请求携带的数据量。

7.2 性能观察指标

跑脚本时重点观察这几个指标：

简单计时代码：

python复制import time

t0 = time.perf_counter()
records = table.search_for_records_where("Material Designation", contains="Steel")
print(f"query returned {len(records)} records in {time.perf_counter() - t0:.2f}s")

7.3 常见性能瓶颈

第一个瓶颈是拉取全表数据。如果表很大，一次拉全量记录再在本地过滤，速度和网络消耗都会很糟糕。正确做法是尽量用服务端过滤条件收窄结果集。

第二个瓶颈是逐条提交。批量写入时，循环里每次 update 一条记录，会产生大量网络往返。改为累积到一定数量再提交，速度能提升一个数量级。

第三个瓶颈是加载超大数据属性。部分属性值本身数据就很大，比如整条应力-应变曲线。如果业务只需要曲线特征值，就不要加载整条曲线。

第四个瓶颈是搜索结果数量限制。某些版本的脚本接口对单次搜索返回的记录数有限制，超出部分需要分页或游标遍历。遇到“明明有几万条记录，脚本只返回前 100 条”的情况，优先怀疑这个限制，查阅当前版本的分页机制。

8. 常见问题与排查方法

排查时先看完整报错信息，不要只看第一行。Scripting Toolkit 报错通常会带上具体记录名或属性名，这些信息能直接定位问题。

9. 最佳实践与使用建议

9.1 脚本工程化

不要把所有逻辑堆在一个文件里。建议拆成三层：

• 配置文件：服务地址、数据库名、表名、批次大小
• 连接模块：封装 Connection 的创建和认证
• 业务脚本：查询、导入、导出等具体任务

连接信息放到配置项或环境变量里，不要硬编码到代码中。脚本提交到代码仓库前，检查是否包含账号密码。

写操作脚本要设计成可以安全重跑。至少要有幂等检查逻辑，最好是支持“预演模式”——只打印将要做的事，不真正提交，确认无误后加参数再执行写操作。

9.2 数据安全与合规

批量修改数据的风险比单条修改高得多。一个大意可能覆盖整张表的关键属性。以下是几条硬性建议：

• 在测试库或训练库完成全部验证，再切到生产库
• 批量更新前，通过脚本或管理员辅助导出原始数据备份
• 删除或覆盖属性这类不可逆操作，必须有独立审批
• 涉及新材料研发数据、客户数据、保密数据时，确认你有权处理和导出
• 脚本和输出文件存放在受控环境，按数据保密级别管理

9.3 从开发到上线

新脚本上线前，至少过一遍以下流程：

1. 在测试库跑通全流程
2. 用小数据集验证查询条件正确性
3. 用预演模式检查将要创建或修改的记录数量
4. 备份相关数据库内容
5. 正式执行，并保留执行日志
6. 在 MI 界面抽查验证结果

把这套流程沉淀成团队规范，脚本化的数据操作才能长久稳定运行。

10. 总结与下一步

Granta MI Scripting Toolkit 最值得尝试的点，是把材料数据管理从“人工点界面”变成“脚本自动跑”。对于批量导入、批量导出、仿真数据对接这类高频重复任务，它的收益非常直接。

拿到环境后，先验证三件事：连接是否通、查询是否准、写入是否被允许。这三个验证做完，基本可以确定后续批量任务能不能落地。

最容易踩的坑有两个：第一个是版本 API 差异，网上搜到的示例代码不一定能直接跑，必须以你当前版本的官方文档为准；第二个是批量任务没有日志和幂等设计，中断后重跑产生重复数据。

下一步可以探索的方向：把这个脚本工具封装成公司内部的数据导入平台；用计划任务定时从试验数据库同步数据到 MI；或者把它集成到 CAE 自动化流程中，实现“选材料 → 取属性 → 提交仿真 → 回写结果”的闭环。

建议从一条最频繁、最痛的数据链路开始做自动化，跑通之后再横向扩展。这个工具的价值，最终取决于你能把多少手工流程交给脚本。