使用 mp-api 0.46.4 进行 Materials Project 有界查询认证、溯源与计算数据限制实战指南【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skillsMaterials Project 是材料科学领域最重要的计算数据库之一但直接对接其 API 时认证方式、字段选择、分块策略、重试与限流行为、缓存与许可义务等细节很容易踩坑。本指南以 scientific-agent-skills 仓库中 pymatgen 技能的 Materials Project API 参考 为骨架结合 mp_query.py 查询 CLI 的源码实现与 测试用例完整讲解如何用官方独立客户端mp-api0.46.4进行有界bounded查询、保留数据溯源provenance、并正确理解计算数据的科学限制。读完本文你将掌握一套可复制、可审计、符合材料数据许可与引用规范的材料数据库查询工作流。版本基线为什么必须锁定客户端与材料计算栈Materials Project 的计算数据会随数据库版本更新而变化API 的字段与签名也会独立演进。因此本文所有代码、参数与结论均绑定一个已验证的版本快照mp-api0.46.42026-06-15 发布官方独立 Materials Project 客户端pymatgen2026.5.4与pymatgen-core2026.7.16材料结构与计算数据处理的底层库三者均要求Python 3.11mp-api声明依赖pymatgen2024.2.20。pymatgen 采用基于日期的版本号PyPI 渲染为带点的日期形式不能把它当作语义化版本去推断兼容性。同时pymatgen包元数据要求pymatgen-core2026.4.16同时锁定两个发行版可以防止pymatgen2026.5.4在安装时静默解析到另一个未来版本的 core。这一点在该技能的 SKILL.md 的已验证快照说明中有明确记录。mp-api0.46.4的包元数据声明了以下直接依赖来自 materials_project_api.mdpymatgen2024.2.20核心结构对象与 I/Omonty2024.12.10通用工具库emmet-core0.87.1数据模型文档定义requests2.23.0HTTP 传输层orjson3.10,4高性能 JSON 解析pyarrow20与deltalake1.4,1.6bulk / delta-table 全量数据集下载路径另有 boto3 与 typing 扩展。由于直接 pin 无法冻结全部传递依赖必须生成并保留锁文件才能复现环境。安装用 uv 创建可复现的环境推荐使用 uv 在项目级创建锁文件对应参考文档中的安装命令uv add pymatgen2026.5.4 pymatgen-core2026.7.16 mp-api0.46.4 uv lock uv sync --frozen该技能在 SKILL.md 中还给出两种环境初始化方式。从零开始uv init --python 3.11 uv add pymatgen2026.5.4 pymatgen-core2026.7.16 mp-api0.46.4 uv lock uv sync --frozen对于一次性、可丢弃的评审环境uv venv --python 3.11 .venv-pymatgen uv pip install --python .venv-pymatgen/bin/python \ pymatgen2026.5.4 pymatgen-core2026.7.16 mp-api0.46.4无论哪种方式都要保存uv.lock、平台信息、Python 版本、包版本与产物哈希因为直接 pin 并不能冻结所有传递 wheel。客户端导入使用独立官方客户端不要用旧版导入路径访问 Materials Project 必须使用独立官方客户端from mp_api.client import MPRester不要照抄旧版 pymatgen 示例中pymatgen.ext.matproj之类的遗留导入。仓库的静态测试 test_static.py 明确断言脚本中不得出现pymatgen.ext.matproj并且 StalenessTests 会扫描 Markdown 文档拒绝过期的安装模式如裸pip install、MAPI_KEY、旧版CifParser.get_structures等已废弃写法。这保证了仓库内的所有示例始终指向当前的 API 形态。认证只使用一个命名密钥访问 Materials Project 需要 API key可从登录后的 Materials Project 控制面板dashboard获取。官方认可的注入方式是环境变量MP_API_KEY由用户的 shell 或会话密钥管理器注入from mp_api.client import MPRester # MPRester 只读取已经注入的 MP_API_KEY。 with MPRester() as rester: pass操作规则非常严格见 materials_project_api.md只使用环境变量MP_API_KEY经 shell/会话密钥管理器注入绝不接受命令行参数形式的密钥绝不把密钥写进代码、notebook、URL、缓存文件或 manifest绝不遍历 dot-env 文件、绝不转储环境变量绝不打印密钥或包含密钥的未脱敏异常除官方 Materials Project API 端点外不向任何地方发送密钥。仓库为这条规则提供了双重验证。静态测试 test_static.py 断言mp_query.py中os.getenv(MP_API_KEY)恰好出现一次且除该行外脚本中不出现任何其他os.environ/os.getenv调用——也就是说查询 CLI 只碰这一个命名密钥。运行级测试 test_scripts.py 进一步验证在未设置MP_API_KEY时执行--executeCLI 会在访问网络、写输出文件之前就以退出码 2 失败且错误报告中明确包含MP_API_KEY提示、不记录密钥本身。异常文本的脱敏由 _common.py 的safe_error_message实现将已知密钥替换为[REDACTED]并截断到 1000 字符。发起任何请求之前先披露查询契约在发生任何网络请求之前必须先向使用者披露以下 8 项内容materials_project_api.md端点与mp-api版本全部过滤器filters精确的响应字段fieldsnum_chunks、chunk_size与最大序列化字节数缓存读写行为输出路径与不覆盖已有文件策略密钥来源按名称绝不按值数据许可、引用方式、溯源与科学限制。MPRester初始化本身就会执行兼容性检查与心跳/数据库版本元数据请求然后才进行有界 summary 搜索。仓库的查询 CLI 会在计划中披露这些请求、禁用带平台详情的 user agent 与本地数据库版本通知日志并记录服务器返回的数据库版本mp_query.py。dry-run 计划器是默认行为不触碰网络、不导入 pymatgen、不读取密钥python skills/pymatgen/scripts/mp_query.py \ --chemsys Li-Fe-O \ --energy-above-hull 0 0.05 \ --fields formula_pretty,energy_above_hull,band_gap,origins \ --limit 25只有显式指定--execute才允许执行已披露的有界网络查询且要求同时提供新的输出路径python skills/pymatgen/scripts/mp_query.py \ --material-id mp-149 \ --fields formula_pretty,structure,origins,last_updated \ --limit 1 --output mp-149.json --execute从 mp_query.py 的query_contract可以看到 CLI 的硬性边界--limit上限 100MAX_RESULTS--fields上限 20MAX_FIELDS--material-id最多重复 100 次MAX_MATERIAL_IDS输出字节上限默认 20 MiBDEFAULT_MAX_OUTPUT_BYTES可配置但不得超过 50 MiBmp_query.pymaterial_id只接受mp-/mvc-前缀加数字的格式字段名只接受字母数字下划线无论用户传什么字段material_id总是会被加入有效字段列表effective_fields搜索参数固定为all_fieldsFalse、num_chunks1、chunk_sizeargs.limit即单次、单分块的有界查询CLI 没有任何隐式结果缓存显式写出的有界 JSON 输出才是可复用产物mp_query.py。输出文件由 _common.py 的checked_output_file校验拒绝 URL、拒绝路径中的..、拒绝符号链接、拒绝覆盖任何已存在文件且要求父目录为已存在的非符号链接目录实际写入通过write_text_new的排他模式open(x)完成保证并发环境下也不会覆盖_common.py。执行后报告会明确回执network_accessed、输出字节数、overwrote_existing: False与api_key_logged: Falsemp_query.py。Summary 搜索材料属性总览的首选入口官方文档将 summary 数据定义为材料的主要属性总览。通过rester.materials.summary.search发起查询from mp_api.client import MPRester with MPRester() as rester: docs rester.materials.summary.search( material_ids[mp-149, mp-13], fields[ material_id, formula_pretty, energy_above_hull, band_gap, origins, last_updated, ], all_fieldsFalse, num_chunks1, chunk_size25, )要点material_ids在当前签名中接受单个 ID 或 ID 列表默认返回SummaryDocPydantic 模型对象列表all_fieldsFalse时只返回fields中列出的字段官方默认是请求全部字段代价高昂因此始终传一个精简的fields列表并限定分块。CLI 的 mock 执行测试test_scripts.py验证了这一点执行时传入的search关键字必须包含num_chunks1与chunk_sizelimit并且MPRester初始化时include_user_agentFalse、notify_db_versionFalse。属性过滤器已核实的参数与易错点以下SummaryRester.search参数已核实可用materials_project_api.mdwith MPRester() as rester: docs rester.materials.summary.search( chemsysLi-Fe-O, elements[Li, O], exclude_elements[F], energy_above_hull(0.0, 0.05), band_gap(0.5, 3.0), is_stableNone, fields[material_id, formula_pretty, energy_above_hull, band_gap], all_fieldsFalse, num_chunks1, chunk_size25, )其他当前可用的过滤器还包括formula、crystal system、density、deprecation、介电范围、弹性范围、金属/直接带隙标志、属性可用性、磁有序、元素/位点计数、空间群、理论态theoretical标志、能量范围、体积与表面属性范围。务必查阅已安装版本的精确签名而不是猜测关键字名。两个高频易错点exclude_elements是元素符号列表不是布尔标志available_fields列出端点可返回的字段但不代表每个字段都能作为过滤器使用with MPRester() as rester: returnable_fields rester.materials.summary.available_fields仓库 CLI 在实际执行时会用available_fields校验用户请求的字段发现无效字段立即拒绝请求mp_query.py避免发出注定失败的请求。序列化用公共 Pydantic 模型接口拒绝 pickle查询结果通过公共模型接口序列化保证模式校验与稳定结构payload [document.model_dump(modejson) for document in docs]然后以严格 JSON写出allow_nanFalse、带字节上限、写往新的输出路径并在输出中包含查询、字段、检索时间、端点、客户端版本以及许可/引用信息。不要使用已废弃的通用字典 shim、pickle或对不可信缓存数据使用通用对象反序列化器。仓库的document_to_jsonmp_query.py实现了同样的约束优先走model_dump(modejson)拒绝无法序列化为对象的结果json_text序列化时强制allow_nanFalse并对键排序_common.py。获取结构区分计算弛豫与实验结构按 material ID 获取结构from mp_api.client import MPRester with MPRester() as rester: structure rester.get_structure_by_material_id( mp-149, finalTrue, conventional_unit_cellFalse, )也可以把structure作为显式字段放进 summary 查询。无论哪种方式都要保留material ID请求的是 final/initial 表示还是 conventional/primitive 表示origins与任务 ID检索时间与数据库版本解析器/API 警告。返回的结构必须在本地验证。Materials Project 结构是计算弛豫表示不等同于实验设定、晶格参数、无序、温度或组分模型——这是下游做结构分析、对称性分析、变换与热力学计算时必须牢记的前提该技能的 SKILL.md 工作流规范同样强调解析器警告、无序/部分占据、氧化态标注的显式处理。Entries 与相图在同一化学体系中构建凸包获取某一化学体系内兼容的能量条目from mp_api.client import MPRester with MPRester() as rester: entries rester.get_entries_in_chemsys( Li-Fe-O, compatible_onlyTrue, conventional_unit_cellFalse, )当前方法还接受use_gibbs、property_data与additional_criteria。官方查询指南展示了通过thermo_types过滤热力学类型的写法with MPRester() as rester: entries rester.get_entries_in_chemsys( Co-N, additional_criteria{ thermo_types: [GGA_GGAU, GGA_GGAU_R2SCAN, R2SCAN] }, )科学上必须注意不要随意混用热力学类型或校正方案correction scheme记录全部参数、entry ID、校正数据、origins 与数据库版本将取回的 entries 本地保存并在离线构建凸包hull。这与技能的整体定位一致本地相图生成器只接受包含每个 entry 总能量eV与溯源信息的严格 JSON schema且明确要求 elemental endpoints and all competing phases must be present不允许混用不同泛函/赝势/磁态/校正约定的原始能量SKILL.md。能带结构与态密度DOS官方便捷方法如下with MPRester() as rester: bands rester.get_bandstructure_by_material_id(mp-149) dos rester.get_dos_by_material_id(mp-149)两个方法在数据不可用时都可能返回None。能带与 DOS 的数值是计算方法依赖的必须保留计算/任务来源、自旋/SOC、路径/网格、泛函与数据库版本。不要把缺失对象当作零带隙或零 DOS——这一条同时是解释性的科学约束也是materials_project_api.md的明文要求。用 origins 保留溯源官方查询指南建议请求origins字段把 summary 属性连接到具体的计算任务with MPRester() as rester: summaries rester.materials.summary.search( material_ids[mp-149], fields[material_id, structure, origins], all_fieldsFalse, num_chunks1, chunk_size1, )origins可以标识某个属性所用的任务对应 thermo 文档的run_type则区分 GGA、GGAU、r2SCAN 等类别。不要假设同一 summary 文档上的所有属性都来自同一次计算或同一个泛函——这正是本文反复强调溯源的根本原因。其他路由按端点访问勿抄旧示例客户端在rester.materials下暴露了端点专属的 resters覆盖 thermo、电子结构、弹性、介电、磁性、声子、表面、XAS、合成相关数据等路由。每个路由的签名与文档模型各不相同必须查阅当前路由文档只请求支持的字段。端点的可用性与 schema 可能独立于 Python 包装器演进因此不要复制旧端点示例、不要臆造过滤器名。错误、重试与限流处理使用当前客户端提供的异常类型from mp_api.client.core.exceptions import MPRestError try: with MPRester() as rester: docs rester.materials.summary.search( material_ids[mp-149], fields[material_id], all_fieldsFalse, num_chunks1, chunk_size1, ) except MPRestError: # 报告一个受控的、凭证已脱敏的失败。 raise官方 0.46.4 客户端源码的行为materials_project_api.md对 HTTP 429、502、504 配置了重试并遵循Retry-After将请求失败包装为MPRestError连接超时时建议缩小请求规模。安全规则依赖锁定客户端的有界重试行为不要自行添加无界重试循环除非官方文档发布数字配额否则不要声称任何数字服务配额超时或响应过大时减少字段/分块大小遇到持续性的授权、schema 或校验错误时停止从任何异常文本中脱敏MP_API_KEY。仓库 CLI 完整落实了上述规则rate_and_error_handling计划段明确声明自定义重试否并如实描述客户端的 429/502/504 重试与Retry-After遵循行为、不假设数字配额mp_query.py所有异常经safe_error_message脱敏后以有界 JSON 报告mp_query.py。缓存策略缓存是数据治理义务缓存能提升可复现性但也会产生数据治理义务。使用缓存前必须披露精确路径、schema、大小上限与保留期缓存键端点、过滤器、字段、客户端版本与数据库版本过期数据是否可以接受许可/引用元数据是否存储结构或贡献者数据。两条红线绝不缓存凭证不检查检索时间与数据库版本绝不把缓存当作最新数据。mp-api为 bulk/delta-table 工作流暴露了本地全量数据集缓存路径而本仓库的 summary 查询 CLI不请求那些下载刻意不使用任何隐藏结果缓存materials_project_api.md。测试也验证了 CLI 的计划输出中result_cache.enabled为Falsetest_scripts.py。许可、署名与引用Materials Project 声明其数据采用CC BY 4.0许可贡献者数据归各贡献者所有。官方 FAQ 指出凡使用 Materials Project 数据、方法或输出均应进行引用。需要保留的内容规范的 Materials Project 引用来自材料/引用页面的属性/工具专属引用数据库版本引用material IDs 与任务/属性来源检索日期与查询条件。计算数据的科学限制缺失不等于零Materials Project 官方明确materials_project_api.md核心属性使用模拟方法在内部计算典型/系统性误差必须依据各属性的发表文献评估PBE 晶格参数常有系统性高估在范德华相互作用描述不佳处层间误差更大PBE 带隙被系统性低估summary/聚合值会随计算与数据库版本的更新而变化空间群取决于symprecMP 流水线通常使用0.1 Å。由此推导出五个不可违背的结论计算稳定性 ≠ 实验稳定性或可合成性预测结构 ≠ 存在性证明缺失数据 ≠ 零一个 material ID 不保证只有一条不可变属性记录引用时必须注明数据库版本与属性方法学。这正是 SKILL.md Materials Project: plan before network 一节反复强调的MP 核心值是计算方法依赖的数据而非实验真理CLI 输出 JSON 中也内置了interpretation_limits数组逐条列出这些限制mp_query.py。最小溯源信封provenance envelope一次合规查询应产出类似下面的溯源信封——绝不含 API key{ retrieved_at_utc: 2026-07-23T00:00:00Z, endpoint: https://api.materialsproject.org/materials/summary/, filters: {material_ids: [mp-149]}, fields: [material_id, formula_pretty, origins, last_updated], limit: 1, client: { mp-api: 0.46.4, pymatgen: 2026.5.4, pymatgen-core: 2026.7.16 }, database_version: record from current MP release metadata, license: CC BY 4.0, citation: https://materialsproject.org/about/cite }仓库 CLI 生成的执行结果 JSON 自动包含完整溯源retrieved_at_utcUTC ISO 时间戳、端点、三个库的版本、服务器返回的database_version、CC BY 许可声明与规范引用链接外加查询快照filters/fields/limit/num_chunks、返回数量与是否可能还有更多结果的诚实标注mp_query.py。mock 测试还验证了数据库版本被正确写入 provenance、密钥绝不进入输出文件test_scripts.py。测试背书的可验证行为仓库用两层测试锁定了本文描述的每一项行为test_static.py 静态检查脚本顶层只允许标准库导入、禁止 pickle/subprocess/eval 等危险原语、mp_query.py只读取MP_API_KEY这一个环境变量、文档与脚本中不存在过期 API 模式、参考文档均带Sources (verified 2026-07-23)核实标记且相对链接可解析test_scripts.py 运行级测试--help在无科学依赖时可运行、dry-run 默认不执行不联网、无密钥执行--execute会在联网/写文件前失败、mock 执行时强制num_chunks1、禁用 user agent 与 db 版本通知、密钥脱敏且输出不含密钥。这两层测试意味着如果你按本文方式调用 mp_query.py在--execute之前不会发生任何网络与凭证访问执行后得到的 JSON 必然带完整溯源、无隐式缓存、绝不覆盖已有文件、绝不泄露密钥。结语把有界查询 溯源 限制意识固化为默认工作流Materials Project API 的正确用法不是发一个请求拿数据而是先披露契约、再有界执行、后完整溯源的三段式流程。结合本仓库的 Materials Project API 参考 与 mp_query.py 的实现你已经掌握了用MPRester做 summary/结构/entries/能带查询的完整签名与易错点、用--execute显式授权与有界输出的 CLI 模式、MPRestError与 429/502/504 重试的边界、CC BY 4.0 下的引用义务以及计算数据 ≠ 实验真值、缺失 ≠ 零的科学底线。将这些规则内化到你的材料数据流水线中每一次查询都会成为可审计、可复现、可引用的科学产物。参考来源均于 2026-07-23 核实本仓库的 materials_project_api.md、SKILL.md、mp_query.py、_common.py以及 test_scripts.py 与 test_static.py外部信息源包括 mp-api 0.46.4 的 PyPI 发布页与官方仓库、Materials Project 官方 Getting Started / Querying data 指南、mp-api 路由参考、官方 FAQ、计算细节页、How to Cite 页与数据库版本页。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考