Granta MI Scripting Toolkit：从材料数据管理到Python自动化工作流

做材料数据工作的人，大概率经历过这样的场景：仿真工程师跑过来说“这个材料的弹性模量到底按哪个值取”，你打开 Excel 翻了半天，发现同一材料存在三个不同版本的数据，谁也无法保证哪个是经过审批的正式状态。轻则重新确认、耽误交付，重则带着错误参数把整个仿真流程跑完，最后追溯问题时要花几倍时间返工。

这就是材料数据管理要解决的工程问题。Granta MI 是 Ansys 旗下用于集中管理材料数据的系统，而 Scripting Toolkit 则是它面向开发者和数据工程师提供的脚本入口。我的判断是：Scripting Toolkit 真正改变的不是单次查询的体验，而是材料数据工作流本身——它把“人和数据库之间的交互”变成了“程序与数据库之间的管道”。这意味着材料查询、批量导入、数据清洗、结果对比、合规报告，都可以从人工操作变成可版本化、可追踪、可自动执行的脚本任务。

这篇文章会从四个层面把 Granta MI Scripting Toolkit 讲清楚：它解决什么问题、核心概念是什么、最小脚本怎么跑通、以及在实际工程中怎么用才不出错。读完你可以搭建第一个可运行的脚本，知道查询和写入材料数据的通用套路，也能避开版本差异、单位换算、权限管理这几类最常见的坑。

1. 从材料数据痛点说起：这篇文章要解决的问题

先不要急着写代码。任何一个入门教程，如果没搞明白“到底在解决什么问题”，学完也会很快忘掉。

材料数据管理在制造业研发体系里，是一个看起来不性感、但一旦出问题就很致命的环节。常见场景有三种。

第一种是仿真参数获取。结构仿真、热仿真、电磁仿真都需要输入材料属性，比如弹性模量、屈服强度、热导率、介电常数。这些数据散落在 Excel、实验报告、供应商规格书甚至个人电脑里，仿真工程师每次取值都要人工确认来源，效率极低。

第二种是研发数据回写。实验室做完一批拉伸试验、疲劳试验，数据格式五花八门，需要人工整理后录入系统。录入过程容易出错，而且没有统一脚本，下一次同样的事情还要重复做一遍。

第三种是合规审计。航空、能源、医疗器械行业对材料来源和性能数据有严格追溯要求。如果数据链路不完整，审计时拿不出可信的证据链，问题就非常严重。

在没有脚本工具的情况下，上述场景的通用做法是：用 GUI 打开 Granta MI 客户端，一条条查记录，或者导出 Excel 再手工处理。遇到数据量大、需要频繁重复的任务时，这种方式基本不可持续。

Scripting Toolkit 的思路很直接：把 Granta MI 的数据访问能力封装成 Python 接口。开发者通过脚本连接服务器、定位数据库、查询记录、读取属性、批量写入，整个过程可以被复现、被审查、被自动化。它把材料数据工程师从“在界面里点点点”的状态，拉回了程序员熟悉的世界：代码、测试、版本管理、定时任务。

所以这篇文章的核心读者是三类人：第一类是仿真工程师/CAE 工程师，想摆脱手工取参数；第二类是材料研发和实验数据管理人员，需要批量导入和整理数据；第三类是数据工程师或 PLM/MDM 系统集成开发者，负责把材料数据接入数据分析或企业应用链路。

哦对，还要说清楚不推荐谁看。如果只是偶尔查一次材料，GUI 客户端已经完全够用，没必要引入脚本依赖和服务器配置。Scripting Toolkit 的价值在于重复、批量、自动化，不是替代单次查询。

2. Granta MI Scripting Toolkit 核心概念与适用场景

在官网文档里，Scripting Toolkit 通常被描述为“提供对 Granta MI 数据进行编程访问的工具包”。它的运行方式并不神秘：底层是通过网络 API 访问 Granta MI 服务器，Python 包把这些接口封装成更方便调用的对象和方法。

要理解这个工具包，先要理解 Granta MI 的数据模型。材料数据不是一堆没有结构的表格，它按照几个层级组织。

最上层是数据库（Database），对应系统中的一个材料数据库。数据库下面有数据表（Table），比如“金属材料主数据表”“聚合物牌号表”“疲劳试验数据表”。每个表里有大量记录（Record），一条记录对应一种材料或一次试验的一条信息。记录上挂着属性（Attribute），属性才是真正存储具体数值和文本的地方，比如抗拉强度 450 MPa、材料状态“调质处理”。一些复杂属性还会保存层级数据，例如应力-应变曲线的多个数据点。

用关系型数据库来类比：Database 类似一个 database 实例，Table 类似数据库表，Record 类似一行数据，Attribute 类似一列字段。但材料数据的复杂之处在于属性类型非常丰富，包括单值、多值、离散参数、函数曲线、图片、链接等，而且数值属性通常还带单位。这就是为什么材料数据管理系统要用专门模型，而不是单纯靠通用数据库表硬扛。

Scripting Toolkit 在访问模型上通常体现为会话（Session）和客户端（Client）两类对象。客户端负责与服务器建立连接、管理认证状态；会话对象代表一次登录后的操作上下文，支持查询表、读取记录、创建记录等操作。不同版本对这些对象的命名和职责划分有过调整，但核心思路一致：先建客户端，再登录拿会话，然后通过会话操作数据。

这里有一个容易混淆的点：Scripting Toolkit 不只是单纯的数据读取工具。它可以写数据、更新数据、运行为自动化任务，也可以和 Jupyter Notebook 结合做数据探索。它和 Granta MI 自带的 Excel 插件、Desktop 客户端的定位有重叠，但不相同。

从行业实践看，Scripting Toolkit 最常见的落地场景包括：批量实验数据导入、材料属性报告自动生成、把 Granta MI 中的数据桥接到仿真前处理脚本、用 Pandas 做材料数据探索和统计分析、以及在企业数据管道中定时同步材料主数据。

3. 环境准备与依赖安装

开始写脚本之前，要确认手里有几样东西。

第一是 Granta MI 服务器地址，通常是一个可访问的 HTTP/HTTPS 地址。第二是有登录权限的账号，并且该账号在你需要操作的数据库上有对应权限。第三是确定要访问哪些数据库和数据表，这个信息最好先从 GUI 或数据管理员那里确认好，不然脚本跑起来会两眼一抹黑。

本地开发环境方面，推荐使用 Python 3.9 及以上版本。Ansys 系工具包对 Python 版本有一定要求，新版本通常要求 3.9+。如果公司有统一 Python 版本管理规范，先按规范走。

建议用虚拟环境隔离依赖，避免和别的项目冲突。命令行操作如下：

bash复制python -m venv granta_env
source granta_env/bin/activate
# Windows 下运行: granta_env\Scripts\activate

接下来安装 Python 包。这里有一个入门阶段最容易懵的地方：包名和导入路径在多个版本中发生过变化。

早期的 Scripting Toolkit 包名是 granta-miscripting-toolkit，导入时使用 GRANTA_MIScriptingToolkit 前缀。后来 Ansys 逐步把包拆分成带 ansys- 前缀的模块，例如用于基础网络连接的 ansys-openapi-common、用于服务器和数据访问的 ansys-grantami-serverapi-openapi 等。新项目原则上优先使用 ansys- 前缀的包，因为这是当前和后续维护的方向。

bash复制pip install ansys-openapi-common ansys-grantami-serverapi-openapi

# 如果公司内部源或旧环境还在使用旧包
# pip install granta-miscripting-toolkit

国内网络环境下如果下载慢，可以临时指定镜像源，例如清华 PyPI 镜像，命令如下：

bash复制pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ansys-grantami-serverapi-openapi ansys-openapi-common

安装完成后，建议用一行代码验证包是否正确导入：

bash复制python -c "import ansys.grantami.serverapi; print('ok')"

如果打印出 ok，说明基础依赖已经就绪。

开发工具方面，Jupyter Notebook 适合做数据探索，PyCharm 或 VS Code 适合做正式脚本开发。本系列示例采用命令行脚本加输出打印的方式，方便跑通最小流程。

4. 登录连接与第一个最小脚本

跑通连接是后续一切操作的前提。连接流程可以理解为三步：创建 HTTP 客户端、创建 Granta MI 服务客户端、登录并取得会话。

这里先给一个最小登录脚本。注意，不同版本的 API 在方法名上可能有差异，但对象职责和数据流是稳定的：Client 负责连接，Session 负责业务操作。

python复制# 文件路径：examples/01_connect.py
from ansys.openapi.common import ApiClient
from ansys.grantami.serverapi import ServerApiClient

def create_session(server_url: str, username: str, password: str):
    # 第 1 步：创建 HTTP API 客户端
    api_client = ApiClient(server_url)

    # 第 2 步：创建 Granta MI 数据服务客户端
    server_client = ServerApiClient(api_client)

    # 第 3 步：登录，获得会话对象
    session = server_client.connect(user_name=username, password=password)
    return session

if __name__ == "__main__":
    session = create_session(
        server_url="https://your-granta-mi-server.com",
        username="your_username",
        password="your_password",
    )
    print("连接成功")
    print(session)

这段代码中的 ApiClient 负责处理底层 HTTP 通信、认证状态和请求会话；ServerApiClient 是面向 Granta MI 服务的高层入口；connect() 会执行登录并返回一个可进行数据操作的会话对象。

第一次运行时，最常见的问题是找不到服务器地址、认证失败或网络不通。如果连接报错，先检查服务器地址是否能直接访问，浏览器能否正常打开登录页，以及账号密码是否使用了企业 SSO 认证。如果企业使用 SSO，登录方式可能不是简单的用户名口令，需要再参考公司内部 IT 提供的集成文档。

跑通登录后，不要急着写业务逻辑。可以对会话对象做一次“能力扫描”，用 Python 的 dir() 函数看看它到底提供了哪些方法。这是一个非常实用的入门技巧，面对不熟悉的 SDK，先浏览对象方法列表，能极大加速理解。

python复制# 文件路径：examples/02_inspect_session.py
methods = [m for m in dir(session) if not m.startswith("_")]
for m in methods:
    print(m)

如果希望脚本不硬编码密码，可以使用环境变量读取。例如在 Linux 或 macOS 下先设置环境变量：

bash复制export GRANTA_MI_USER=your_username
export GRANTA_MI_PASS=your_password

然后在 Python 代码里读取：

python复制import os

username = os.environ["GRANTA_MI_USER"]
password = os.environ["GRANTA_MI_PASS"]

注意，密码不要提交到 Git 仓库，也不要在代码里明文写死。对安全敏感的企业，这一步会有明文审计风险。

5. 查询与读取材料数据

连接成功后，下一步通常是读取数据。读取过程的核心数据流是：定位数据库，定位数据表，过滤记录，读取属性。

这里要提前做好一个心理准备：不同版本的 Scripting Toolkit，方法名确实不完全一样。快速入门时，与其对着不熟悉的版本硬套旧代码，不如把握好流程，再根据你实际安装版本的官方文档对方法名做微调。下面的示例代码展示了完整的流程结构：

python复制# 文件路径：examples/03_query_records.py
# 重点理解数据流：数据库 -> 数据表 -> 记录 -> 属性
# 具体方法名以当前安装版本的官方文档为准

def load_material_records(session, database_name: str, table_name: str, name_prefix: str):
    # 第 1 步：定位数据库
    databases = session.get_databases()
    database = next(d for d in databases if d.name == database_name)

    # 第 2 步：在数据库中定位数据表
    tables = session.get_tables(database)
    table = next(t for t in tables if t.name == table_name)

    # 第 3 步：按名称前缀过滤记录
    records = session.get_records(
        table,
        where={"name": {"like": f"{name_prefix}%"}},
    )
    return records

if __name__ == "__main__":
    session = create_session("https://your-mi-server.com", "user", "password")
    records = load_material_records(
        session,
        database_name="材料主数据库",
        table_name="金属材料",
        name_prefix="Al",
    )
    print(f"查询到 {len(records)} 条材料记录")
    for record in records[:5]:
        print("记录名称:", record.name)

读取属性时要注意两个细节。

第一个是属性类型。材料属性不仅有数值型，还有文本、整数、日期、多值、离散选择等类型。代码中读取属性时最好先确认属性的数据类型，再决定怎么解析。很多新手把数值属性当字符串处理，最后做单位换算时踩坑。

第二个是单位。Granta MI 的数值属性通常会绑定单位系统。读取出来的数值可能带有一个“单位上下文”，如果你要做跨数据库对比或输入到仿真软件，必须先统一单位。比如应力类属性，可能有的记录存 MPa，有的存 ksi，直接拿数值比较没有意义。正确的做法是读取时指定统一输出单位，或者在代码里显式换算。

读出来的记录如果要进一步分析，常见做法是转成 Pandas DataFrame。例如可以先把记录和所需属性名整理成列表，再构建 DataFrame：

python复制import pandas as pd

def records_to_dataframe(records, attribute_names):
    rows = []
    for record in records:
        row = {"record_name": record.name}
        for attr_name in attribute_names:
            # 读取属性值；实际写法取决于你的记录对象 API
            row[attr_name] = record.attributes[attr_name].value
        rows.append(row)
    return pd.DataFrame(rows)

attributes = ["弹性模量", "屈服强度", "材料状态"]
df = records_to_dataframe(records, attributes)
print(df.head())

这种转换一旦建立，材料数据就能直接进入 Pandas 生态，做统计、画图、对比都方便很多。这也是很多人把 Scripting Toolkit 和 Jupyter 组合使用的原因：一个脚本完成从数据库到分析结果的全过程。

查询性能方面，不要一次性导出超大表的所有记录再过滤。能下推到服务器端的过滤条件，尽量在查询参数里完成。服务端过滤比客户端过滤快一个数量级，而且不会因为加载过多数据把内存打爆。如果确实需要全量导出，建议分段批量拉取，后续再逐批处理。

6. 批量写入与更新数据

读取数据只是第一步，不少团队更关心的是“能不能把实验数据批量写回 Granta MI”。答案是可以，但写数据比读数据要谨慎得多，因为每一条写入都可能影响其他人的数据分析和合规记录。

写入流程通常包含四个环节：创建记录或定位已有记录、设置属性值、提交事务、验证结果。下面是一个概念完整的写入示例：

python复制# 文件路径：examples/04_write_data.py
# 写入前必须确认：属性名、属性类型、单位、数据库版本定义
# 以下代码演示数据流，方法名以当前安装版本的官方文档为准

def write_lab_results(session, table, rows):
    created_records = []
    for row in rows:
        # 在目标表中创建一条新记录
        new_record = table.create_record(row["record_name"])

        # 设置文本属性和数值属性
        new_record.set_attribute("材料牌号", row["material_grade"])
        new_record.set_attribute("抗拉强度", row["tensile_strength"])
        new_record.set_attribute("屈服强度", row["yield_strength"])
        new_record.set_attribute("试验温度", row["test_temperature"])

        created_records.append(new_record)

    # 统一提交，保证事务一致性
    session.commit(created_records)
    return created_records

这段代码有一个容易被忽略的关键点：commit 之前的所有修改都还没有真正落到数据库里。提交操作把一批变更统一生效，这既是为了性能，也是为了保证数据一致性。如果中途某条记录写入失败，你可以选择整体回滚或排查后重试，而不会出现“写了一半”的脏数据状态。

真正在企业里做批量写入时，还要考虑幂等性。什么叫幂等？就是同一批数据重复执行，不会产生重复记录。比如你每天从实验管理系统同步一次试验数据，如果脚本不能识别“这条记录已经存在”，第二天再跑一遍就会出现两条一模一样的记录。解决思路有两个：一是写入前先查目标记录是否存在，存在则更新而非新建；二是利用系统记录的唯一标识字段做去重判断。

写入操作的安全要求必须反复强调：首选在测试数据库上验证；没有测试库，也要先用最小数据量、临时记录验证属性对应关系；确保账号只拥有本次任务所需的最小写入权限；保留提交前和提交后的数据快照，方便回滚。

材料数据直接关联产品设计决策，一旦写错，影响范围可能超出数据本身。谨慎永远比效率优先。

7. 运行结果与验证方法

写完脚本，怎么知道数据读对了、写对了？不能只看脚本没有报错就结束。推荐下面几个验证步骤。

第一步，核对数量。查询场景下，脚本输出的记录条数要和 GUI 里看到的一致。如果脚本返回 10 条而 GUI 显示 25 条，先检查过滤条件，再看账号权限是否覆盖了全部数据。

第二步，核对属性值。挑几条已知材料或已知试验记录，交叉检查关键属性。比如一个材料的抗拉强度历史值是 480 MPa，脚本读出来是 69.6 ksi，那单位换算就对不上。使用标准化单位输出，能减少很多低级错误。

第三步，写入后立即查询。对批量写入场景，在 commit 之后重新查询最新数据，确认记录数量、关键属性都符合预期。这一步最好写成自动检查，而不是肉眼查看。

第四步，保留追踪信息。给脚本增加日志，记录执行时间、操作人、连接服务器、操作数据库、写入记录数、提交结果。这样即使出现问题，也能通过日志回溯是哪一次操作、哪一批数据导致的。

如果运行中出现异常，第一反应应该是查看完整堆栈信息，而不是只盯着最下面一行错误描述。Python 堆栈会告诉你错误发生的确切文件和行号，再配合刚才提到的日志，排查效率会高很多。

8. 常见问题与排查思路

下面是 Scripting Toolkit 入门阶段出现频率较高的几类问题，整理成表格，方便直接对照。

如果遇到的方法名和本文示例不一样，不用慌。Granta MI 脚本工具包的 API 在版本迭代中有过调整，尤其从旧包切换到 ansys- 新包时，导入路径、类名和部分方法名都会变化。处理办法是打开官方快速入门文档，对照你当前版本找最新写法。不要从旧项目里直接复制代码，也不要从网上随机找过时代码硬套。

还有一个容易被忽略的问题：企业环境经常使用自签名的 HTTPS 证书或代理服务器。如果连接时报 SSL 相关错误，可能需要把企业 CA 证书安装到本机 Python 信任库，或按 IT 规范配置信任链。这里不要随便禁用 SSL 验证，安全第一。

9. 最佳实践与工程建议

Scripting Toolkit 入门不难，难在把脚本真正做成可靠、可维护的工程工具。这里结合材料数据项目的特点，整理一组工程建议。

第一，统一依赖管理。给每个项目建立独立虚拟环境，使用 requirements.txt 或 pyproject.toml 锁定包版本。Scripting Toolkit 依赖较多，版本升级容易引发 API 变化，锁版本是避免“过了三个月脚本跑不起来”的基本手段。

第二，凭据与配置分离。服务器地址、数据库名、表名放在配置文件中；用户名密码放环境变量或密钥服务系统。脚本代码本身应该是“无密钥”的，这样才可以安全地提交到 Git 仓库。

第三，先探测、后定位。登录后先打印对象方法列表，或者用 GUI 确认好数据库、表、属性名称，再编写正式查询。真实项目里因为名称拼写差异浪费的时间，远比功能调试多。

第四，强制事务边界。写入场景把“构造数据、修改属性、提交事务”三个环节分开写；提交前留出检查断点。宁可代码长一点，也不要写出一团分不清边界的逻辑。

第五，小批次执行。无论是读取还是写入，先处理 10 条记录验证数据流，再扩展到全量。批量任务建议设定单批大小，避免单次请求数据量过大导致内存溢出或服务器超时。

第六，自动化验证。把“查询后核对数量”“写入后反查”写成脚本中的断言，而不是人工目测。这一步可以与 CI 集成，让每天跑的数据同步任务在错误发生时及时告警。

第七，衔接下游工具链。Scripting Toolkit 最值得投入的地方是作为材料数据管道的一环。把读取结果转成 DataFrame，把批量导入逻辑封装成函数，把报告生成流程参数化，效果远好于写一次性脚本。

第八，保留审计日志。记录每次脚本执行的服务器、账号、数据库、时间、成功状态和影响记录数。材料数据经常面临质量审计，日志就是数据可信度的证明。

10. 总结与后续学习方向

Granta MI Scripting Toolkit 的入门核心，不是死记某个版本的 API 写法，而是理解“连接客户端、获取会话、定位数据库、操作记录属性、管理事务”这条稳定数据流。版本会更新，方法名会调整，但数据流不会变。掌握了这个骨架，换任何版本都能快速上手。

下一步建议你这样做：先拿一个真实但低风险的查询场景跑通登录和读取，比如“读取某张表前 50 条记录的牌号和供应商属性”。跑通后，再试着把结果转成 DataFrame 做一次简单统计。确认读取链路没问题后，再进入写入链路，并且先在测试库验证。

如果你还想继续深入，有几个方向值得关注：一是记录列表（Record Lists）相关功能，它用来管理一批跨表记录，适合构建材料选型清单；二是数据导出 API，适合做跨数据库的大批量数据导出；三是和 Pandas、Matplotlib、MAB 等数据分析和机器学习工具的组合用法。材料数据自动化这个方向，越早把基础数据流跑通，后续能省下来的时间就越可观。

最后提醒一句：材料数据影响设计决策，脚本只是工具，数据正确性和流程可靠性才是一切的底线。先从小场景、小批次开始，把每一步验证做扎实，再逐步扩大自动化范围。这样建立的脚本，才是可以长期信赖的工程资产。