README

PHP客户端，用于连接到COMPREDICT V1 REST API。

要了解更多信息，请访问官方文档网站： https://compredict.de

需求

• PHP 7.2或更高版本
• cUrl扩展已启用

要使用基本认证连接到API，您需要以下信息：

• 从Compredict用户仪表板获取的API密钥。
• 账户的用户名。
• (可选) 用于发送结果的回调URL

安装

使用以下Composer命令从Packagist上的Compredict供应商安装API客户端

 $ composer require compredict/ai-sdk
 $ composer update

命名空间

以下所有示例都假设使用以下命名空间声明导入Compredict\API\Client类到作用域中：

use Compredict\API\Algorithms\Client as Compredict;

配置

要在您的PHP代码中使用API客户端，请确保您可以通过Composer的vendor/autoload.php钩子访问Compredict\API。

将您的凭据提供给静态配置钩子，以便为连接到Compredict平台上的商店准备API客户端

基本认证

$compredict_client = Compredict::getInstance(
    'Your-token',
    'Your-callback-url',  //optional
    'path-to-ppk',  //optional
    'passphrase-of-the-ppk'  //optional
);

访问算法（GET）

列出集合中的所有算法

$algorithms = $compredict_client->getAlgorithms();

foreach ($algorithms as $algorithm) {
    echo $algorithm->name;
    var_dump($algorithm->getTemplate());
}

访问单个算法

$algorithm = $compredict_client->getAlgorithm('ecolife');

echo $algorithm->name;
echo $algorithm->description;

算法预测（POST）

某些资源支持通过向集合发送POST请求创建新项目。可以通过传递表示新资源的数组或stdClass对象到全局创建方法来完成此操作

// pass as array
$X_test = [
    "feature_1" => [1, 2, 3, 4], 
    "feature_2" => [2, 3, 4, 5]
];

$algorithm = $compredict_client->getAlgorithm('algorithm_id');
$result = $algorithm->predict($X_test);

// pass as file_path
$X_test = "/path/to/file.parquet";

$algorithm = $compredict_client->getAlgorithm('algorithm_id');
$result = $algorithm->predict($X_test, file_content_type="application/parquet");

根据算法的计算需求，结果可以是

• 任务：包含用户可以稍后查询以获取结果的作业ID。
• 预测：包含算法+评估的结果

您可以通过以下方式识别算法将处理任务调度到队列或立即发送结果：

echo $algorithm->getResponseTime();

或动态地

$result = $algorithm->predict($X_test, $evaluate="True");

if($result instanceof Compredict\API\Algorithms\Resources\Task){
    echo $result->getCurrentStatus();
    while($result->getCurrentStatus() != Compredict\API\Algorithms\Resources\Task::STATUS_FINISHED){
        sleep("3"); # wait some time.
        $result->update(); // check Compredict for updated results.
    }
    echo $result->success;
    var_dump($result->predictions);
}

如果您设置了callback_url，则计算完成后，结果将自动通过POST发送给您。

每个算法都有其自己的评估方法，用于根据数据评估算法的性能。您可以通过调用以下方法来识别评估指标

$algorithm->evaluations;  // associative array.

在运行算法时，如果设置了evaluate = True，则算法将使用默认参数进行评估。为了调整这些参数，您必须指定一个包含修改后参数的关联数组。例如

$evaluate = [];
$evaluate['rainflow-counting'] = [];  // name of the evaluation method
$evaluate['rainflow-counting']["hysteresis"] = 0.2;  // evaluation method parameter 1
$evaluate['rainflow-counting']["N"] = 0.2;  // evaluation method parameter 2

$result = $algorithm->predict(X_test, evaluate=$evaluate);

数据隐私

当计算在Compredict中被排队时，计算结果将临时存储三天。如果数据是私有的，并且组织在Compredict中存储此类数据存在问题，则可以使用RSA加密数据。Compredict允许用户在仪表板中添加RSA公钥。然后，Compredict将使用公钥来加密存储的结果。作为回报，SDK将使用提供的私钥来解密返回的结果。

Compredict仅在以下情况下加密结果：

• 用户在仪表板中提供公钥。
• 在预测函数中将encrypt参数指定为True。

以下是一个示例

// First, you should provide public key in COMPREDICT's dashboard.

// Second, Call predict and set encrypt as True
$result = $algorithm->predict($X_test, $evaluate=True, $encrypt=True);

if($result instanceof Compredict\API\Algorithms\Resources\Task){
    echo $result->getCurrentStatus();
    while($result->getCurrentStatus() != Compredict\API\Algorithms\Resources\Task::STATUS_FINISHED){
        sleep("10"); # wait some time.
        $result->update(); // check Compredict for updated results.
    }
    echo $result->is_encrypted;  // will return True
}

处理错误和超时

由于任何原因，API核心中的HTTP请求可能并不总是成功。

每个方法在发生错误时都会返回false，因此在根据方法调用结果采取行动之前，您应该始终检查这一点。

在某些情况下，您还需要检查请求失败的原因。这通常发生在您尝试保存某些未正确验证的数据时。

$algorithms = $compredict_client->getAlgorithms();

if (!$algorithms) {
    $error = $compredict_client->getLastError();
    echo $error->code;
    echo $error->message;
}

在错误上返回false，并使用错误对象提供上下文，对于编写快速脚本是有益的，但不是用于更大规模和长期应用的最高效解决方案。

另一种错误处理方法是将API客户端配置为在发生错误时抛出异常。请注意，如果您这样做，您需要在代码中自己捕获和处理异常。客户端的异常抛出行为是通过使用failOnError方法控制的。

$compredict_client->failOnError();

try {
    $orders = $compredict_client->getAlgorithms();

} catch(Compredict\API\Algorithms\Error $error) {
    echo $error->getCode();
    echo $error->getMessage();
}

抛出的异常是Error的子类，表示客户端错误和服务器错误。API文档中包含响应代码的文档，列出了客户端可能遇到的全部可能的错误条件。

验证SSL证书

默认情况下，客户端将尝试验证由COMPREDICT AI Core使用的SSL证书。在不希望这样做或使用未签名证书的情况下，您可以使用verifyPeer开关关闭此行为，这将禁用后续所有请求的证书检查。

$compredict_client->verifyPeer(false);