神农Alpha API

使用 NMM ID 获取神农Alpha知识库中一味药材的当前公开知识。单条查询支持匿名限额访问；批量查询需要登录态或 API 密钥。正式程序接入建议使用自己的密钥，以便归属用量与审计。

curl --fail-with-body \
  'https://shennongalpha.westlake.edu.cn/api/v1/knowledge/nmm-0001'

接口	用途	认证
GET /api/v1/knowledge/{nmm_id}	完整知识 JSON／下载	公开读取
POST /api/v1/knowledge/batch	一批查询 1–20 个 NMM ID	登录态或 API 密钥
GET /api/name/search	标准化名称搜索	公开读取
GET /api/name/all	三类名称词表	公开读取
GET /api/snnmm	SNNMM 药材身份查询	公开读取

API 地址不加 /zh 或 /en 语言前缀。完整知识保留原始多语正文；切换本站界面语言不会改变 JSON 的内容语言。

GET /api/v1/knowledge/{nmm_id}

nmm_id 格式为 nmm- 加四位小写字母或数字，例如 nmm-0001。返回当前已公开的 SNNMM、文本章节、成分、关联靶点、关联疾病和引用书目，不含审核草稿、账号信息或全部历史版本。

加上 download=1 即可下载同一份结构的 JSON，响应附带文件名。知识页的“下载知识”按钮使用此接口，成分与关联数据直接包含在 JSON 内，无需另取成分文件。

curl --fail-with-body \
  'https://shennongalpha.westlake.edu.cn/api/v1/knowledge/nmm-0001?download=1' \
  --output nmm-0001.json

正常返回 200；ID 格式错误返回 400，有效格式但无对应知识返回 404。单条读取失败会返回错误，不将失败伪装成空知识。

POST /api/v1/knowledge/batch

请求头使用 Content-Type: application/json。正文只能包含 nmm_ids，接受 1–20 个不重复的有效 ID；空列表、重复 ID、21 个及以上或额外字段返回 400，不会静默截断。

下面的 SHENNONGALPHA_API_KEY 是调用方环境变量，值为你在设置 → API 密钥创建并保存的密钥。此处公开的是变量名，不是真实密钥。

curl --fail-with-body \
  'https://shennongalpha.westlake.edu.cn/api/v1/knowledge/batch' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${SHENNONGALPHA_API_KEY}" \
  --data '{"nmm_ids":["nmm-0001","nmm-01g8"]}'

响应包含 schema_version、complete、requested 和 results，结果顺序与请求一致。每个成功项为 {nmm_id, status: 200, data}，其中 data 是完整的单条知识对象；失败项为 {nmm_id, status, error: {code, message}}。

HTTP 200 只表示批次已处理。必须检查顶层 complete 和每项 status；部分条目 404、413 或 503 时，其他条目仍可成功。只重试需要重试的失败项，避免重复读取成功项。

完整知识使用 schema_version: "shennongalpha.knowledge.v1"。这是数据契约版本，与网站软件版本分别管理。

字段	含义
_id	NMM ID
source	来源名称“神农Alpha知识库”及知识页 URL
metadata	公开标签、警示（如有）、创建与知识更新时间
knowledge.sections	保留目录标题和嵌套结构的公开知识章节
references	正文和成分引用的书目；resolved=false 表示尚未解析到书目
completeness	当前公开知识的读取完成状态、关联记录数和未解析引用
association_note	成分介导关联的解释边界
content_version	内容的 SHA-256 版本标识，用于比较快照是否变化
exported_at	本次导出时间；仅导出时间变化不会改变内容版本

每个章节含 toc_id、toc_heading、description、value。嵌套章节位于 value.sections；实际内容位于 value.content，由 value.template 区分类型：

template	content 主要字段
snnmm	nmm_id、snnmm、nmm_hierarchy、synonyms
mlmd	id、sna_corpus_id、revision、corpus（原始多语文本）
ingredients	nmm_id、items、total、relationship: "nmm_compound"
related_targets	同上，relationship: "compound_mediated_association"
related_diseases	同上，relationship: "compound_mediated_association"

以下是 nmm-0001 成分章节 value.content 的真实响应节选（2026-10-27）。为便于阅读，items 仅展示首条，total 保留当时全部记录数；实际接口返回全部记录，内容会随知识库更新。

{
  "nmm_id": "nmm-0001",
  "items": [
    {
      "pubchem_cid": 323,
      "pubchem_compound_name": "coumarin",
      "cas_registry_number": "91-64-5",
      "canonical_smiles": "C1=CC=C2C(=C1)C=CC(=O)O2",
      "ref": {
        "url": "http://herb.ac.cn/Detail/?v=HERB004520&label=Herb",
        "herb_id": "HERB004520",
        "sna_ref_id": "sna-ref-15"
      }
    }
  ],
  "total": 132,
  "relationship": "nmm_compound"
}

pubchem_cid 是数值编号；成分 ref 保留来源对象，例如 URL、来源数据库编号及 sna_ref_id，也可能为 null。

靶点记录包含 pubchem_cid、ncbi_gene_id、official_symbol、official_full_name、pubmed_pmid；疾病记录包含 pubchem_cid、mesh_id、mesh_heading、pubmed_pmid。

• 同一成分的多个来源逐条保留，total 是记录数，未必是独立成分数。
• 章节 value=null 表示没有已发布的章节内容；items=[] 表示成功查询但无关联记录。缺少字典名称时保留 ID，名称可为 null。
• completeness.complete=true 表示本次当前公开知识范围读取完成，不表示学术知识无缺漏。单条导出使用一致的数据快照；批次中不同条目各有自己的快照。
• content_version 用于内容比对，不是数字签名；metadata.last_updated_date 与内容版本分别保留，导出时间也不等于知识更新时间。

靶点与疾病是成分介导的关联，不能直接当成整味药材的作用或临床疗效证据。保留 PMID 或书目不代表已经核验论文内容。

GET /api/name/search

参数	说明
name_type	必填，见下方四类
q	搜索词，默认空字符串
page	整数页码，默认 1，范围 1–100000
limit	每页数量，默认 20，范围 1–100

name_type 可选 species_origins（物种基原）、medicinal_parts（用药部位）、processing_methods（炮制方法）、special_descriptions（特殊描述）。建议以小页请求，按 total 翻页。

curl --fail-with-body --get \
  'https://shennongalpha.westlake.edu.cn/api/name/search' \
  --data-urlencode 'name_type=species_origins' \
  --data-urlencode 'q=Artemisia annua' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=5'

返回 {q, page, limit, total, results}。物种结果含 la、zh 等字段；其他三类含 en、zh、explanation，炮制方法另有 en_full、category。无匹配时 total=0、results=[]。

GET /api/name/all?name_type=medicinal_parts 返回完整小词表，不分页。此接口仅支持 medicinal_parts、processing_methods、special_descriptions，不支持全量物种；响应结构同搜索，q=""、page=1、limit=total。

GET /api/snnmm

以下查询字段每次选一个：nmm_id（NMM ID）、nmmsn（英文系统名）、nmmsn_zh（中文系统名）、nmmgn（英文通用名）、nmmgn_zh（中文通用名）。兼容旧参数 nmmid，新接入建议用 nmm_id。

curl --fail-with-body --get \
  'https://shennongalpha.westlake.edu.cn/api/snnmm' \
  --data-urlencode 'nmm_id=nmm-0001'

返回 {total, results}，每项含 nmm_id、snnmm、nmm_hierarchy、synonyms 等身份信息。无匹配时返回 200、total=0、results=[]；缺少查询字段或同时指定多个查询字段返回 400。

只需要身份匹配时使用此接口；需要章节正文、成分和关联数据时使用完整知识接口。

单条完整知识、Name 与 SNNMM 可公开读取。批量完整知识支持：

1. 本站已登录用户的同源请求，随请求携带本站会话 Cookie。
2. 服务端应用使用 Authorization: Bearer <API 密钥>。

登录后进入设置 → API 密钥，每个账号先支持 一个未撤销密钥。可以创建、重新生成或撤销，选择 30、90 或 365 天有效期。完整值只在生成时展示一次，数据库仅保存不可逆摘要。密钥过期后可重新生成；重新生成立即替换旧密钥，已在处理中的请求可能完成。

创建时选择读取权限：knowledge:read（完整知识与下载）、names:read（Name 搜索、词表和提示）、snnmm:read（身份查询）。密钥不能用于修改知识、管理用户或管理密钥。缺少权限返回 403；无效、过期或撤销的密钥返回 401，不会退回匿名访问。

服务端应用可使用个人 API 密钥接入；需要独立管理的服务可由管理员配置服务身份、服务密钥和独立配额。密钥保存在调用程序服务端，不写入浏览器脚本、公开仓库、URL 或日志。

接口未开放跨域浏览器调用。其他网站应从服务端调用神农Alpha；本站网页继续使用登录态，无需把个人密钥放进网页。

调用审计

相关查询接口返回 X-Request-Id，用于关联调用记录和排查错误。设置页面可查看自己的最近 90 天记录；管理员可查看所有用户及服务的记录，并调整额度、停用 API 访问。

记录包括调用身份、密钥编号、接口、时间、消耗额度、状态、批量失败项数和耗时，不保存真实密钥、搜索词或知识正文。匿名请求无法归属具体用户；服务密钥标识调用服务，不代表该服务内部的具体用户。调用方可保存返回的 X-Request-Id，在自己的任务记录中关联平台调用记录。密钥创建、重新生成、撤销和额度调整另有操作记录。

完整知识、下载、Name 搜索／词表／名称提示以及 SNNMM 查询均接入同一套认证、权限、配额和审计。公开网页浏览继续可用；其他内部接口不因此获得密钥访问权限。

调用	消耗额度单位
单条完整知识／下载	1
批量完整知识	请求的 NMM ID 数，最多 20
Name 搜索	每请求 20 条容量计 1 单位，向上取整；默认 1，最多 5
Name 完整小词表	20
SNNMM 查询／Name 名称提示	1

已接纳请求中的未找到或读取失败条目也计入成本。个人密钥和登录态共享账号额度，重新生成或撤销后创建密钥均不会重置额度。

默认限制维度	每分钟条数	每日条数
匿名来源	60	1,000
同一 IP（所有身份合计）	120	10,000
同一账号或独立服务身份（默认，可由管理员调整）	300	20,000

所有适用限制同时生效，采用固定 UTC 时间窗口；同一网络出口可能共享 IP 配额。密钥还受对应身份额度约束；实际限额以设置页面和响应为准：

• X-RateLimit-Limit：适用分钟额度的最严格值。
• X-RateLimit-Remaining：分钟窗口内的最小剩余额度，不代表日余额。
• X-RateLimit-Cost：本次请求消耗的额度单位。
• Retry-After：429 后需要等待的秒数。等待后带随机间隔重试，避免同时重发。

同一 IP／身份最多 2 个在途请求，全服务默认最多 8 个。批量正文上限 4 KiB，单条 JSON 上限 8 MiB，整批响应上限 24 MiB，每个关联章节最多 10,000 行；超过限制会明确报错，不截断为“完整”结果。较大批次可能耗时约 70 秒，调用方可设置 90 秒超时，并按需缩小批次。

完整知识接口的应用错误通常使用下列结构；code 适合程序判断，message 用于说明，客户端不应依赖消息语言。

{
  "error": {
    "code": "authentication_required",
    "message": "批量查询需要登录或知识 API 服务密钥。"
  }
}

HTTP 状态	含义与处理
400	ID／正文／查询参数无效，修正后请求
401	需要认证或密钥无效
403	缺少读取权限、账号／API 被停用，或登录态请求来源不匹配
404	未找到对应知识；批量中见每项状态
405	请求方法错误
408	上传请求正文超时
413	请求或结果过大，缩小批次；单条过大需联系平台
415	批量接口要求 application/json
429	额度或并发受限，遵循 Retry-After
503	暂时不可用或读取超时，稍后重试

无效 JSON、超大批量请求体由应用返回明确错误并记录审计；网关或网络层错误仍可能返回非 JSON 内容。先检查 HTTP 状态和 Content-Type，再解析响应。旧版 Name、SNNMM 的错误结构为 {code, message, user_message}，其中 code 是 HTTP 状态数值，与完整知识接口的字符串错误代码不同。

ShennongSearch 是访问神农Alpha的 Python SDK，与主站使用同一数据服务。官方 HTTP 接口说明以本页为准；SDK 的安装、类型模型和 DataFrame 用法见 ShennongSearch Python SDK 文档及源码仓库。

SDK 封装了 Name 和 SNNMM 查询。下例兼容旧版 SDK（匿名限额访问）；是否支持 api_key 参数以安装版本为准。需要明确按个人密钥计量时，可使用下方 HTTP 示例。

from shennongsearch import ShennongSearchClient

with ShennongSearchClient() as client:
    identity = client.snnmm.get(nmm_id="nmm-0001")
    print(identity.total)

    names = client.name.species_origins.search(
        q="Artemisia annua", page=1, limit=5
    )
    print(names.total)

当前 SDK 尚未封装完整知识单条和批量接口，可直接使用 HTTP。以下带密钥的单条示例只依赖 Python 标准库。请先配置 SHENNONGALPHA_API_KEY 环境变量：

import json
import os
from urllib.request import Request, urlopen

url = "https://shennongalpha.westlake.edu.cn/api/v1/knowledge/nmm-0001"
request = Request(url, headers={
    "Authorization": "Bearer " + os.environ["SHENNONGALPHA_API_KEY"]
})
with urlopen(request, timeout=90) as response:
    knowledge = json.load(response)

print(knowledge["_id"], knowledge["content_version"])
print(knowledge["completeness"])