麻省理工学院数据到AI实验室的开源项目。

Sibyl-API

用于理解和交互ML模型的REST-API端点。

概述

Sibyl-API提供易于理解的ML模型解释和流畅交互的API端点。

要开始使用Sibyl-API，请按照以下说明或文档中的说明设置您的Sibyl数据库。从那里，您可以轻松进行模型预测，获取和修改模型特征的详细信息，并获得关于您的模型及其预测的各种解释。

安装

需求

Sibyl-API需要MongoDB版本6或7。

要安装MongoDB，请遵循此处的说明。

从PyPi安装

Sibyl-API可以从pypi安装

pip install sibyl-api

从源代码安装

Sibyl-API使用Poetry进行依赖管理。如果您尚未安装Poetry，请前往poetry安装指南并根据说明安装poetry。运行以下命令以确保poetry已激活。您可能需要关闭并重新打开终端。

poetry --version

然后，您可以克隆此仓库，并通过运行poetry install从源代码安装它

git clone https://github.com/sibyl-dev/sibyl-api.git
cd sibyl-api
poetry install

快速入门

按照以下步骤开始使用内置的Ames住房数据集示例。您可以通过运行以下命令准备和加载数据集

sibyl prepare-sample-db

⚠️此函数将覆盖localhost:27017上名为housing的任何现有数据库)

现在，您可以运行Sibyl-API并使用示例数据集

poetry run sibyl run -D housing -v

一旦Sibyl-API运行，您就可以在localhost:3000/apidocs手动访问和测试您的API

准备数据库

Sibyl-API使用基于MongoDB的数据库系统。我们提供了几种设置数据库的方法。

准备数据

所需输入

至少，sibyl-API需要以下输入（可以是DataFrame或csv，请参阅以下创建选项）

entities：一个包含要解释的实体的表。每一行应对应于一个单一观测值。

列

• eid (必需)：唯一标识符，指定此观测值对应哪个实体
• row_id：唯一标识符，指定观测ID。一起，eid和row_id应唯一标识每个观测值。
• label：此观测值的真实标签
• [FEATURES]：用于预测的每个特征的附加列。这些列的名称应与模型中使用的特征相同。

样本表

features：一个包含用于预测的特征的表。每一行应对应于一个单一特征。

列

• feature (必需)：特征的名称
• type (必需)：特征类型。这可以是categorical、numerical或boolean
• description：特征的描述
• negative_description：特征不存在时的描述。仅适用于布尔特征
• values：特征的可能的值列表。仅适用于分类特征。

样本表

realapp：一个经过序列化的 pyreal.RealApp 对象。该对象用于生成模型的解释。有关设置细节，请参阅pyreal 文档。

可选输入

此外，您还可以使用以下方式进一步配置 API：

config：一个配置文件（YAML 或 python 字典），用于指定附加设置。有关详细信息，请参阅我们的配置文档。

categories：一个用于预测的类别表。每一行应对应一个单独的类别。

列

• category（必需）：类别的名称
• description：类别的描述
• color：用于类别的颜色
• abbreviation：用于类别的缩写

创建 Mongo 数据库

使用 prepare-db 脚本

在准备数据库之前，请确保启动您的 mongodb 服务

将 sibyl/db/config_template.yml 复制并填写您的配置。将所需数据放在公共目录中。

接下来，使用以下命令运行预处理脚本：

sibyl run prepare-db [CONFIG_NAME].yml [DIRECTORY]

其中 [CONFIG_NAME].yml 是您的配置文件路径，[DIRECTORY] 是包含您的数据的目录。

使用设置向导

目前，设置向导仅在从源安装时可用。首先，使用以下命令安装可选设置依赖项：

poetry install --with setup

然后，使用以下命令运行设置向导：

poetry run streamlit run setup-wizard/main.py

运行 API

安装库后，您可以使用以下命令在本地运行 API：

poetry run sibyl run -v -D [DATABASE_NAME]

或者，以开发模式运行

poetry shell

sibyl run -E development -v -D [DATABASE_NAME]

您可以在本地通过http://localhost:3000/apidocs 访问您的 API

贡献指南

我们感谢所有类型的贡献！有关说明，请参阅我们的贡献指南。