Granta MI Scripting Toolkit 导出数据从环境准备到批量导出的完整实战这次我们不看花哨的 AI 生成而是看一个材料工程师、结构工程师和数据管理岗经常要用的东西ANSYS Granta MI 的 Scripting Toolkit。简单说Granta MI 是 ANSYS 旗下的材料信息管理系统用来存储聚合物、金属、复合材料、涂层等一系列材料数据。而 Scripting Toolkit 是它的官方 Python 脚本工具包让你不通过 Granta MI 桌面客户端而是直接用 Python 脚本去查询、读取、导出数据。对做材料数据归档、CAE 仿真前处理、知识库迁移、批量导出报表的人来说这个工具能省掉大量手工点鼠标的时间。这篇博客会讲清楚四件事Scripting Toolkit 能做什么、环境怎么搭、脚本怎么跑通完整导出流程、批量导出时最容易踩哪些坑。文章会给出可落地的代码示例和排查思路不绕弯子直接进入主题。如果你最近在做 Granta MI 数据迁移、需要把数据库里的材料卡片批量导出成 Excel/CSV或者是想用 Python 自动化读取 Granta MI 里的材料属性表那么这篇文章适合你。不需要很深的前置知识有 Python 基础就能跟下来。1. 核心能力速览先把 Granta MI Scripting Toolkit 的定位和常见能力列成一张表方便你快速判断是否能解决当前问题。能力项说明项目类型ANSYS Granta MI 官方提供的 Python 脚本工具包核心功能连接 Granta MI 数据库、浏览层级记录、读取属性值、导出材料数据可导出数据字符串、数字、离散值、表格数据、时间序列、链接记录等常见输出格式通过 pandas 导出 CSV、Excel或自行生成 JSON、XML运行环境需要安装 Python支持 Windows 和 Linux 场景以官方文档为准启动方式命令行执行 Python 脚本或 Jupyter Notebook 交互式运行是否需要 Granta MI 客户端部分操作需要 Granta MI 底层服务可用桌面客户端不是必需但需要数据库访问权限是否支持批量任务支持可以通过脚本遍历记录、批量读取、写入文件是否支持 API通过 python 包提供编程接口没有 RESTful API 也需要通过脚本调用适合场景材料数据归档、批量导出、CAE 前处理、数据库审计、知识库迁移从实际使用来看Scripting Toolkit 最有价值的一点是把 Granta MI 的数据访问从“图形界面操作”变成了“可重复执行的脚本任务”。你不必再在客户端里一层层展开树形目录、找属性、手动导出 Excel而是可以用一个脚本完成全部动作。需要提醒的是不同版本的 Granta MI 数据库和不同版本的 Scripting Toolkit接口细节会有差异。所以下面给出的代码是通用实战思路具体部署时要以官方安装包附带的文档为准。2. 适用场景与使用边界2.1 适合谁用材料数据管理员需要定期从 Granta MI 导出数据表、生成统计报表。CAE 仿真工程师需要把 Granta MI 中的材料曲线、属性数据取出来转为仿真软件能识别的输入文件。数据迁移人员从旧数据库向新环境迁移需要批量抽取历史记录。Python 开发者负责给团队开发内部数据工具需要把 Granta MI 的数据接入到其他系统。2.2 能解决什么问题手工导出效率低的问题一条记录数据量可能包含几十个属性、多张表格手工导出太慢。数据一致性差的问题不同人用不同方式导出容易漏字段、漏记录。重复导出的问题每月、每周固定要导出写成脚本后可以自动执行。数据落入下游系统的问题导出成 CSV/Excel/JSON 后方便 pandas 处理。2.3 不适合什么场景如果你只需要在线查看材料数据用 Granta MI 客户端更合适。如果你需要修改 Granta MI 的数据模型、管理用户权限Scripting Toolkit 不是主要入口。如果你不懂 Python也没有时间学那学习成本会高于直接使用客户端。2.4 合规与安全边界Granta MI 里存放的企业材料数据通常有保密要求。脚本导出时要注意必须先确认数据使用权限尤其是涉及第三方材料供应商数据时要检查许可协议。从 Granta MI 导出的数据如果被复用要注意版权和商业授权约束。不要通过脚本绕过权限控制获取不可见数据。不要把公司内部材料库完整导出后放到公网或非授权系统。在测试环境验证脚本时优先使用脱敏数据或样例数据库。这是工程数据安全底线也是职业风险红线必须放在操作之前。3. 环境准备与前置条件在写脚本之前先确认本机环境是否满足要求。下面是一套通用的检查清单具体版本号以官方文档为准。3.1 操作系统Granta MI Scripting Toolkit 官方主要支持 Windows 环境因为 Granta MI 企业版本身多部署在 Windows Server 上。Linux 环境下能否运行取决于是否有 Linux 版本的连接库。更稳妥的做法是先在 Windows 上验证。3.2 Python 环境建议使用 Python 3.8 以上版本64 位。可以使用 Anaconda 或官方 Python 安装包。安装后检查版本python --version建议创建独立虚拟环境避免依赖冲突。python -m venv grana_env grana_env\Scripts\activateWindows PowerShell 下激活虚拟环境grana_env\Scripts\Activate.ps1如果执行策略限制可以先Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass3.3 安装 Scripting Toolkit常见安装方式是通过 pip 安装官方包pip install granta-mi具体包名和版本以官方文档为准。有些版本会提供离线安装包可以通过 GUI 安装向导完成安装和配置。安装后可以验证导入import granta.mi as gmi print(gmi.__version__)如果这一步报错通常说明 Python 环境不对、包名不匹配或者安装路径有问题。请先确认包名是否正确。3.4 数据库访问信息连接 Granta MI 需要以下信息Granta MI 服务器地址形如https://granta.example.com/mi_servicelayer。用户名和密码或者域账号。数据库键名形如MI_Materials。数据库 schema 名。这些信息通常由 Granta MI 管理员提供。3.5 网络与端口脚本运行时需要访问 Granta MI 的服务层接口。因此防火墙需要放行对应 HTTP/HTTPS 端口常见 443并且本机到服务器的网络要通。测试网络连通性ping granta.example.com如果服务器地址不是 IP要确保 DNS 解析正常。3.6 磁盘空间导出数据如果涉及大量材料曲线、表格附件磁盘空间要有预留。建议至少预留 10GB 以上具体取决于导出量。4. 安装部署与启动方式Scripting Toolkit 不像 ComfyUI 或 WebUI 那样需要启动 Web 服务。它是以库的方式被 Python 调用。所以“启动”其实就是“在 Python 脚本或 Jupyter Notebook 里调用它”。4.1 通过脚本文件运行创建一个 Python 文件比如export_granta.py然后在命令行执行python export_granta.py4.2 通过 Jupyter Notebook 交互运行适合测试阶段。安装 Jupyterpip install jupyter jupyter notebook在浏览器中新建 Notebook逐步验证连接、查询、导出。4.3 最小连接示例下面的代码是一个最小连接示例不导出任何数据只测试能否连接服务器并读取当前用户。from granta.mi import GrantaMI # 连接 Granta MI 服务层 session GrantaMI.connect( base_urlhttps://granta.example.com/mi_servicelayer, usernameyour_username, passwordyour_password, ) print(Connected:, session.whoami()) session.close()如果你的环境配置了 Windows 域认证连接方式会不同。以官方文档为准。连接成功说明环境基本就绪。接下来可以进入正式导出。5. 功能测试与效果验证为了让整个过程可验证建议第一次只导出一条记录确认数据完整后再扩大到全库或批量目录。5.1 查看数据库与根目录Granta MI 的数据是以树形层级组织的。先查看数据库下的根节点。from granta.mi import GrantaMI session GrantaMI.connect( base_urlhttps://granta.example.com/mi_servicelayer, usernameyour_username, passwordyour_password, ) # 指定数据库 db session.get_database(MI_Materials) # 获取根节点 root db.get_root() print(Root:, root.name) # 子记录 children root.get_children() for c in children: print(c.name)5.2 读取一条记录的属性Granta MI 中每条记录有多个属性属性可以是日期、字符串、数字、离散选项也可以是表格、超链接、时间序列等。下面读取指定记录的单值属性record db.get_record_by_id(some_record_id) # 读取属性名例如 Density prop record.get_attribute(Density) value prop.value print(value)如果属性值是带单位的数据prop record.get_attribute(Density) print(prop.value, prop.unit_symbol)5.3 导出表格属性数据Granta MI 常见的一类属性是“表格属性”对应多行多列数据例如应力应变曲线。record db.get_record_by_id(some_record_id) # 表格属性名称 table_prop record.get_attribute(Tensile Stress-Strain) table table_prop.value # 通常返回 pandas DataFrame print(table.head())如果table是 DataFrame直接导出table.to_csv(stress_strain_curve.csv, indexFalse)这个场景是 Scripting Toolkit 导出数据的核心价值所在把材料曲线、表格数据直接转成 pandas 格式方便持久化。5.4 遍历所有记录并导出当需要导出某个分类下的全部记录时要遍历子记录。records [] def walk(records, node): for child in node.get_children(): if child.is_folder(): walk(records, child) else: records.append(child) walk(records, root) print(Total records:, len(records))这种递归遍历是常见的目录扫描方式。5.5 完整导出脚本示例下面给出一段完整的批量导出脚本思路把每个记录的名称、ID、若干关键属性导出到一个 DataFrame再写为 Excel。import pandas as pd from granta.mi import GrantaMI ATTRIBUTE_NAMES [Density, Melting Temperature, Thermal Conductivity] def extract_record_info(record): info { record_id: record.record_guid, name: record.name, path: record.path, } for attr_name in ATTRIBUTE_NAMES: try: attr record.get_attribute(attr_name) info[attr_name] attr.value except Exception as e: info[attr_name] None print(f[WARN] Failed to read {attr_name} for {record.name}: {e}) return info def export_all_records(db, output_pathmaterial_export.xlsx): root db.get_root() rows [] def walk(node): for child in node.get_children(): if child.is_folder(): walk(child) else: rows.append(extract_record_info(child)) walk(root) df pd.DataFrame(rows) df.to_excel(output_path, indexFalse) print(fExported {len(df)} records to {output_path}) if __name__ __main__: session GrantaMI.connect( base_urlhttps://granta.example.com/mi_servicelayer, usernameyour_username, passwordyour_password, ) db session.get_database(MI_Materials) export_all_records(db) session.close()这段脚本解决了最典型的“把数据库里材料记录的关键属性批量导出成 Excel”的问题。建议第一次运行前先把ATTRIBUTE_NAMES改成你自己数据库里实际存在的属性名。5.6 判断是否导出成功日志无异常输出。输出的 Excel/CSV 文件行数大于预期记录数的一半最好等于记录数。抽查几条记录和 Granta MI 客户端里看到的数据一致。单位已经处理不要在导出后出现单位不一致问题。5.7 输出质量不稳定的常见原因属性值为空属性类型不匹配。某些记录缺少该属性导致异常。同一属性在不同记录中的单位不同。表格属性为空时导出会出现空 DataFrame。处理方式写脚本时统一做空值检测避免空属性漏数据。6. 接口 API 与批量任务Scripting Toolkit 本质上是一个 Python SDK所以“API 调用”指的是在脚本中调用对象方法而不是 HTTP 接口。如果你想要把导出能力包装成 HTTP 服务给团队用可以自己写一个 FastAPI/Flask 服务。6.1 脚本方法调用示例前面已经演示了session.connectdb.get_rootrecord.get_childrenrecord.get_attribute这些都是最常见的 API 形式。建议参考官方文档查具体参数。6.2 包装成 HTTP 接口如果你需要让团队成员通过浏览器或 Postman 触发导出可以用 FastAPI 包装一层。from fastapi import FastAPI, HTTPException from granta.mi import GrantaMI app FastAPI() app.post(/export) def export_records(request: dict): base_url request.get(base_url) username request.get(username) password request.get(password) db_name request.get(db_name) output_path request.get(output_path, export.xlsx) try: session GrantaMI.connect( base_urlbase_url, usernameusername, passwordpassword, ) db session.get_database(db_name) # 执行导出逻辑 session.close() return {status: success, output_path: output_path} except Exception as e: raise HTTPException(status_code500, detailstr(e))注意生产环境中不要把密码直接放在请求体里建议使用密钥管理或环境变量。6.3 批量任务的目录设计批量导出时最忌讳的是所有文件都堆在一个目录里。建议按材料和数据类型分层output/ ├── 2025-03-10_export/ │ ├── metals/ │ │ ├── steel_001/ │ │ │ ├── properties.csv │ │ │ ├── stress_strain.csv │ │ └── aluminum_001/ │ └── polymers/ │ ├── polymer_001/ │ └── polymer_002/脚本中创建目录from pathlib import Path def ensure_dir(path: str): Path(path).mkdir(parentsTrue, exist_okTrue)6.4 任务日志与失败重试批量任务跑挂是常态。加日志是关键。import logging import time logging.basicConfig( filenameexport.log, levellogging.INFO, format%(asctime)s %(levelname)s %(message)s, ) def export_with_retry(record, max_retries3): for attempt in range(max_retries): try: export_single_record(record) logging.info(fOK: {record.name}) return True except Exception as e: logging.warning(fAttempt {attempt1} failed: {record.name}, {e}) time.sleep(2) logging.error(fFAILED: {record.name}) return False6.5 定时执行如果你需要每周自动导出可以配合 Windows 任务计划程序或 Linux cron。热词里提到的cron表达式就是这一类。在 Windows 下可以这样创建计划任务schtasks /Create /TN GrantaExport /TR python D:\scripts\export_granta.py /SC WEEKLY /D FRI /ST 18:00这样每周五 18:00 自动导出。7. 资源占用与性能观察7.1 内存占用Scripting Toolkit 在读取属性时数据会加载到 Python 进程内存中。如果某个表格属性非常大例如几百万行的实验数据一次性读入内存可能导致内存不足。观察方法Windows 任务管理器查看 Python 进程内存。脚本中打印当前内存占用import os import psutil print(psutil.Process(os.getpid()).memory_info().rss / 1024 / 1024, MB)7.2 网络耗时Granta MI 数据可能在远端服务器每次读取属性都是一次网络请求。所以大量记录遍历时瓶颈通常在网络延迟而不是 CPU。优化方式只读取需要的属性。不要反复重新连接 session。分批导出避免一次性拉取过多记录。通过官方 API 的批量读取能力减少请求次数。7.3 大规模导出建议如果要导出几千条记录建议先用小范围测试跑通再全量跑。否则脚本中有个小 bug全量跑一遍要浪费很长时间。小范围测试样本只导出根目录下的前 10 条记录。只导出某个分类节点下的记录。只导出 2 个属性。7.4 连接释放Granta MI 的连接资源是有限的。长时间占用连接会影响其他人使用数据库。脚本结束前要session.close()。如果脚本中途异常退出连接可能残留。可以通过重新启动脚本释放。7.5 降低资源占用的实践使用生成器逐条处理而不是把所有记录一次性放入列表。每导出一定数量做一次内存清理。单独跑表格属性导出不要和单值属性导出混在一个超大任务里。8. 常见问题与排查方法问题现象可能原因排查方式解决方案导入 granta.mi 报错包未安装或包名不对pip list查看已安装包按官方文档安装正确包名连接超时服务器地址错误、端口不通ping 服务器telnet 端口检查网络路由和防火墙登录失败用户名/密码错误或没有权限用 Granta MI 客户端验证账号确认账号权限无法指定数据库数据库名不正确或账户无权限查看官方可用数据库列表向管理员申请访问权限get_attribute返回空属性名不存在或记录中该属性为空在客户端中查看属性名使用日志打印属性名清单表格数据导出后乱码编码问题查看 Excel 文件编码CSV 使用utf-8-sigExcel 使用 openpyxl导出的 Excel 没有主键没有把 record ID / GUID 写入 DataFrame检查导出列显式添加record_id和name列批量任务中途卡住部分记录访问异常或服务器压力大查看日志定位卡住的记录加异常处理、失败重试、设置超时读取大型表格时内存飙升数据量过大监控内存变化分批读取只查需要的列脚本结束后 session 未关闭异常退出查看连接数使用 try/finally 或 with 上下文管理8.1 乱码问题如果导出的 CSV 用 Excel 打开出现乱码常见原因是没有使用 UTF-8 BOM。解决方法是df.to_csv(output.csv, indexFalse, encodingutf-8-sig)如果是写 Excel建议使用to_excel而不是直接写 CSV因为 Excel 中 CSV 编码兼容问题更多。8.2 主键缺失问题Granta MI 中每条记录在数据库里有唯一标识通常是record_guid或record_id。导出时把它作为主键列避免下游分析时无法对应原始记录。df pd.DataFrame([{record_id: r.record_guid, name: r.name} for r in records])8.3 XML/JSON 自定义导出如果你需要导出成 XML而不是 CSV/Excel可以基于记录属性做序列化。import json def record_to_json(record): output {id: record.record_guid, name: record.name} for attr in record.attributes: try: output[attr.name] attr.value except Exception as e: output[attr.name] None return output with open(export.json, w, encodingutf-8) as f: json.dump(records_data, f, ensure_asciiFalse, indent2)这里提示一点如果属性值是 DataFrame 类型需要先转成列表否则 JSON 序列化会失败。8.4 DBeaver 等其他数据库导出工具的参考热词里出现了 DBeaver 导出数据没有主键、MySQL 导出乱码等问题。这不是本篇重点但如果你的 Granta MI 底层数据本身被其他数据库工具管理要特别注意导出前确认表结构主键是否存在。确认数据库字符集和文件编码一致。大数据量导出建议使用数据库原生导出功能而不是 GUI 工具。Granta MI 的 Scripting Toolkit 不是直接连底层数据库而是通过服务层访问所以上面这些数据库细节可以作为背景参考但排查主线还是回到 Scripting Toolkit 本身。9. 最佳实践与使用建议9.1 第一次先小范围验证不要一开始就跑全库导出。先用一条记录、一个属性、一个表格验证流程。确认数据完全符合预期后再放大到批量任务。9.2 保留一套最小可运行配置把连接信息写入环境变量或配置文件中不要把密码硬编码到脚本里。set GRANTA_BASE_URLhttps://granta.example.com/mi_servicelayer set GRANTA_USERNAMEyour_username set GRANTA_PASSWORDyour_password脚本中读取import os base_url os.environ.get(GRANTA_BASE_URL) username os.environ.get(GRANTA_USERNAME) password os.environ.get(GRANTA_PASSWORD)这样既安全又方便不同环境切换。9.3 统一数据管理习惯建议把输入参数、脚本、输出结果分层管理granta_export/ ├── config.ini ├── scripts/ │ └── export_main.py ├── output/ │ └── 2025-03-10/ └── logs/ └── export.log9.4 批量导出加增量机制如果数据库数据持续更新每次全量导出会很慢。可以记录上次导出的时间或 ID 偏移量只导出新增或变动的记录。具体要看 Granta MI 是否提供最近修改时间查询接口有的话优先用。9.5 数据质量校验导出完成后要做数据质量检查空值率是否异常。数量级是否正确。单位是否统一。是否存在重复记录。关键属性是否全部取到。9.6 合规提醒所有导出数据必须确认授权范围。涉及商业保密数据、客户项目数据时不要存放到公共网盘或个人设备。导出文件要加密访问权限最小化。9.7 脚本异常处理每个读取操作都要有 try/except防止其中一条记录异常导致整个任务中断。把失败的记录记到日志里结束后统一处理。10. 总结与下一步Granta MI Scripting Toolkit 的核心价值就是把材料数据库中的读取、查询、导出流程从手工操作变成可复用脚本。对于需要定期导出材料数据的团队来说它能显著减少重复劳动同时让导出动作标准化、可审计。第一次使用建议先验证三件事能否成功建立连接。能否读取一条记录的指定属性。能否把表格属性导出成 CSV/Excel。这三步跑通后再考虑递归遍历、批量导出、定时任务、接口封装。最容易踩的坑也是三个属性名拼写和实际数据库不一致导致大量空值。大型表格属性一次性全部读入内存导致内存溢出。网络中断或某条记录异常导致整个批量任务中断。解决办法分别是写脚本前先查字典属性名清单分批读取数据加入失败重试和任务日志。如果你接下来要做的不仅是导出还想把 Granta MI 数据接入到仿真流程、企业知识库或材料推荐系统那么思路可以继续延伸导出 CSV/Excel 只是第一步更好的方式是直接基于 Scripting Toolkit 写一层统一的数据访问接口让下游系统通过接口取数而不是各自维护导出文件。这样既避免数据重复拷贝也能保证数据源一致。建议收藏备用等真正要跑 Granta MI 数据导出时按这个流程一步步操作能省不少时间。