Reasoner API的验证工具
项目描述
推理验证器
本软件包提供软件方法，用于使用 任何版本 的 翻译器推理 API (TRAPI) 和 生物链模型 来为翻译器组件（例如知识提供者和自主中继代理）提供服务。
使用软件包
Python 依赖
推理验证器现在需要 Python 3.9 或更高版本（某些库依赖项现在强制要求这样做）。
安装模块
可以直接从 pypi.org 使用（Python 3）pip 或 pip3 安装该模块：
pip install reasoner-validator
从源代码安装和使用模块
自版本 3.1.6 以来，该项目使用 poetry 依赖管理工具 来协调其安装和依赖项。
在安装 poetry 并克隆项目后，可以在可用的 poetry shell 中运行 poetry 安装
git clone https://github.com/NCATSTranslator/reasoner-validator.git
cd reasoner-validator
poetry use 3.10
poetry shell
poetry install
注意，目前 poetry env 可以设置为 Python 3.10 或 3.11。
此安装还会安装测试依赖项（在 pyproject.toml 中的 poetry 'dev' 组）和文档依赖项（在相应的 poetry 'docs' 组中）。如果您不希望这些依赖项产生开销，则可以排除这些 poetry 组依赖项的安装。
poetry install --without dev,docs
如果您计划运行 Web 服务 API，则可以使用可选的 Web 组安装它。
poetry install reasoner-validator --with web
针对 ARS UUID 结果(*) 进行验证或使用本地 TRAPI 请求查询
有一个本地脚本 trapi_validator.py，可以运行 TRAPI 响应验证，针对生物医学知识翻译器 "自主中继系统" (ARS) 的 PK（UUID）索引查询结果、本地 JSON 响应文本文件或针对直接指定的 TRAPI 端点的本地触发的 临时 查询请求。
注意最好在由 poetry install 创建的 poetry shell 中运行。
对于脚本使用，键入
./trapi_validator.py --help
（*）感谢 Eric Deutsch 为此脚本的原型代码
运行测试
运行可用的单元测试并生成覆盖率报告
poetry run pytest --cov
注意，poetry 自动使用任何现有的虚拟环境，但您也可以进入 poetry 默认创建的虚拟环境。
poetry shell
# run your commands, e.g. the web service module
exit # exit the poetry shell
使用 Poetry shell 命令可以在没有 poetry run 前缀的情况下运行测试。我们将继续这种方式。
% poetry shell
(reasoner-validator-py3.9) % pytest --cov
在 HTML 页面上运行详细的覆盖率报告
pytest --cov --cov-report html
在 http://localhost:3000 上提供服务
python -m http.server 3000 --directory ./htmlcov
本地构建文档
以下所有路径均相对于根项目目录。如果需要，首先应重新生成验证代码 Markdown 文件（即，如果 codes.yaml 被修订）。
cd reasoner_validator
python ./validation_codes.py
然后本地构建文档
cd ../docs
make html
生成的 index.html 和描述程序化 API 的相关页面现在可以在 docs 子文件夹 _build/html 中查看。
作为 Web 服务运行验证
推理验证器作为一个简单的 Web 服务提供。可以直接运行该服务或作为 Docker 容器运行。
API
该 Web 服务有一个单一的 POST 端点 /validate，接受简单的 JSON 请求体，如下所示
{
"trapi_version": "1.4.1",
"biolink_version": "3.5.0",
"target_provenance": {
"ara_source": "infores:aragorn",
"kp_source": "infores:panther",
"kp_source_type": "primary"
},
"strict_validation": true,
"response": "{<some full JSON object of a TRAPI query Response...>}"
}
请求体由包含两个顶级标签的 JSON 数据结构组成
- 可以给一个可选的
trapi_version标签赋值，该值表示要验证的消息的 TRAPI 版本，以 SemVer 字符串的形式表达（如果省略，则默认为 'latest'；部分 SemVer 字符串将被解析为它们的 'latest' 次要版本和补丁版本）。此值还可以是 GitHub 分支名称（例如，'master'）。 - 可以给一个可选的
biolink_version标签赋值，该值表示要验证的消息知识图语义内容的 Biolink 模型版本，以 SemVer 字符串的形式表达（如果省略，则默认为支持的 'latest' Biolink 模型工具包版本）。 - 一个可选的
target_provenance，它包含一个对象字典（示例见下），指定在 TRAPI 查询结果中预期恢复的 ARA 和 KP infores 指定的知识源（通过 infores CURIE 指定）和预期的 KP provenance 源类型，即 'primary' 意味着 KP 被标记为 'biolink:primary_knowledge_source'。作为可选项，根 "target_provenance" 或任何子标签都可以省略（默认为 None）。 - 一个可选的
strict_validation标志（默认：None 或 'false'）。如果为 'true'，则遵循严格的验证规则，例如将category、predicate和attribute_type_id的类型为abstract或mixin的使用视为错误。 - 一个 必需的
message标签应具有完整的 JSON TRAPI 响应 作为其值进行验证（见下面的示例）
直接运行 Web 服务
首先安装 Web 特定的依赖项，如果尚未安装（例如，通过上面的 --all-extras）
poetry install --extras web # or poetry install --all-extras
该服务可以直接作为 Python 模块运行。以下是如何直接运行 Web 服务模块。
python -m api.main
转到 http://localhost/docs 查看服务文档，并使用简单的 UI 输入 TRAPI 消息进行验证。
典型输出
以下是一个预期输出的示例，如果将以下 TRAPI 响应 JSON 数据结构发布到 /validate 端点
{
"trapi_version": "1.4.2",
"biolink_version": "4.1.5",
"response": {
"message": {
"query_graph": {
"nodes": {
"type-2 diabetes": {"ids": ["MONDO:0005148"]},
"drug": {"categories": ["biolink:Drug"]}
},
"edges": {
"treats": {"subject": "drug", "predicates": ["biolink:treats"], "object": "type-2 diabetes"}
}
},
"knowledge_graph": {
"nodes": {
"MONDO:0005148": {"name": "type-2 diabetes"},
"CHEBI:6801": {"name": "metformin", "categories": ["biolink:Drug"]}
},
"edges": {
"df87ff82": {"subject": "CHEBI:6801", "predicate": "biolink:treats", "object": "MONDO:0005148"}
}
},
"results": [
{
"node_bindings": {
"type-2 diabetes": [{"id": "MONDO:0005148"}],
"drug": [{"id": "CHEBI:6801"}]
},
"edge_bindings": {
"treats": [{"id": "df87ff82"}]
}
}
]
},
"workflow": [{"id": "annotate"}]
}
}
通常可以收到如下 JSON 验证结果的响应体
{
"messages": {
"Validate TRAPI Response": {
"Standards Test": {
"info": {
"info.query_graph.edge.predicate.mixin": {
"global": {
"biolink:treats": [
{
"edge_id": "drug[biolink:Drug]--['biolink:treats']->type-2 diabetes[None]"
}
]
}
}
},
"skipped": {},
"warning": {},
"error": {
"error.query_graph.edge.predicate.invalid": {
"global": {
"biolink:treats": [
{
"edge_id": "drug[biolink:Drug]--['biolink:treats']->type-2 diabetes[None]"
}
]
}
}
},
"critical": {}
}
}
},
"trapi_version": "v1.4.2",
"biolink_version": "4.1.5"
}
为了最小化验证消息中的冗余，消息在字典中按两个级别唯一索引
- (codes.yaml 记录的) 点分隔的验证代码路径字符串
- 对于具有模板参数的消息，通过一个强制性的 'identifier' 字段（如果模板有一个或多个参数化字段，则该字段预期存在于模板中）
OpenTelemetry 和 Jaeger
注意：OpenTelemetry 在此代码版本中暂时禁用（稍后更新）
可以通过设置环境变量 TELEMETRY_ENDPOINT 为一个合适的跟踪收集端点（例如 Jaeger）来监控 Web 服务以使用 OpenTelemetry（也可以参见 Translator SRI Jaeger-Demo）。
注意：当前的系统 Docker (Compose) 设计仅支持使用内部 Jaeger 容器进行 OpenTemplate 跟踪，可能需要进一步改进才能启用使用外部遥测收集器。
在 Docker 中运行 Web 服务
Reasoner Validator Web 服务可以在 Docker 容器中运行，使用 Docker Compose。
首先，从根项目目录中构建本地 Docker 容器
docker-compose build
然后运行服务
docker-compose up -d
再次转到 http://localhost/docs 查看服务文档。
停止服务
docker-compose down
当然，用户可以根据需要自定义上述 docker-compose 命令。请注意，Docker 实现假定使用 uvicorn
变更日志
早期版本摘要和当前变更日志请参阅此处。
代码限制（暗示未来工作？）
- 2.2.0版本之后的推理验证器的发布可能无法（如果可能的话，可靠地）验证1.3.0之前的TRAPI JSON数据模型
- Biolink模型发布 <= 2.4.8 与 3.0.0 验证：推理验证器使用Biolink模型工具包。实际上，该工具包至少与Biolink模型从2.#.#到3.#.#的结构性变化（对'规范'谓词的标记）不向后兼容：0.8.10++工具包将 <= 2.4.8 模型谓词报告为'非规范'。
- 本版本推理验证器网络服务将检测TRAPI 1.0.*版本，但不力求与它们完全向后兼容（考虑到TRAPI 1.0.*现在完全无关）。
- 网络服务验证不执行TRAPI消息结果部分的深度验证
- 验证仅对图的前1000个节点和100条边进行，以保持验证时间可控（这可能导致图覆盖不完全）
- Biolink模型工具包尚未缓存，因此在使用过程中更改模型版本将导致结果出现一些延迟
- 验证器服务尚未深度验证消息知识图中非核心节点和边的槽内容
- 验证器服务尚未尝试验证查询图节点和边的'约束'（例如
biolink:Association等domain和range约束） - 除非为给定节点提供关联的'类别'参数，否则不会验证查询图节点的'id'。一般来说，查询图验证可以进一步阐述。
- 系统应利用推理器Pydantic模型
核心贡献者
- 感谢Patrick Wang，他在CoVar（一个为生物医学数据翻译器做出贡献的创业团队）期间创建了Reasoner-Validator项目的原始实现。
- 感谢Kenneth Morton（CoVar）对最新代码的审阅。
- 该项目目前正在由Richard Bruskiewich（Delphinai公司，SRI团队为翻译器做出贡献）扩展和维护。
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解更多关于 安装包 的信息。