dergus/clarifai-php

此包的最新版本（1.2.2）没有提供许可证信息。

Clarifai API的PHP客户端

维护者

详情

github.com/dergus/clarifai-php

源代码

安装: 17

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 3

分支: 15

1.2.2 2017-04-18 07:02 UTC

Requires

Requires (Dev)

Unknown License d594ffa19ec07796357882aa60f556848f1262de

This package is not auto-updated.

Last update: 2024-09-20 20:21:35 UTC

README

Travis Build Status StyleCI Status codecov Packagist Version MIT License

PHP的Clarifai API客户端

这是一个100%经过单元测试和（大部分）功能齐全的非官方Clarifai PHP客户端

Clarifai是一家在视觉识别方面表现出色的公司，它为企业和开发者解决现实世界的问题。

composer require darrynten/clarifai-php

PHP 7.0+

基本用法

API相当简单，由输入、概念和模型组成。

定义

输入

您向服务发送输入（图像），它返回预测。除了接收输入的预测外，您还可以“保存”输入及其预测以供以后搜索。您还可以“保存”带有概念的输入以供以后训练自己的模型。

模型

Clarifai提供了许多不同的模型，它们以不同的方式“看待”世界。一个模型包含一组概念。一个模型只会看到它包含的概念。

有时您希望有一个以您的方式看待世界的模型。API允许您做到这一点。您可以创建自己的模型，并使用自己的图像和概念对其进行训练。一旦训练它以按照您期望的方式“看待”，您就可以使用该模型进行预测。

您不需要很多图像就可以开始。我们建议从10张开始，根据需要添加更多。

概念

概念在创建使用您自己的概念的自定义模型中起着重要作用。概念还有助于您搜索输入。

当您将概念添加到输入中时，您需要指示该概念是否存在于图像中或不存在。

功能

这是项目的初步框架，仍在进行中。

请在提交包含您所涵盖功能的pull请求时在此readme中勾选每个部分的复选框。

应用程序基础

  • 使用Guzzle进行通信
  • 该库具有100%的测试覆盖率
  • 该库支持框架无关的缓存，因此您不必担心使用此包的包将最终使用哪个框架。

客户端尚未100%完成，仍在进行中，详情见下文。

结构在很大程度上受到官方JS客户端的启发

身份验证

访问通过oauth2处理。

您需要使用您的客户端ID和密钥初始化客户端。

$this->clarifai = new Clarifai('clientId', 'clientSecret');

预测

这是一个使用预测调用的基本库用法示例。模型名称为aaa03c23b3724a16a56b629203edc62c

include 'vendor/autoload.php';

$clarifai = new \DarrynTen\Clarifai\Clarifai(
    CLIENT_ID,
    CLIENT_SECRET
);

$modelResult = $clarifai->getModelRepository()->predictUrl(
    'https://samples.clarifai.com/metro-north.jpg',
    \DarrynTen\Clarifai\Repository\ModelRepository::GENERAL
);

echo json_encode($modelResult);

响应（摘要）将是

{
  "status":{
     "code":10000,
     "description":"Ok"
  },
  "outputs":[
     {
        "id":"db1b183a95a042d3bd873f8ca69ae2e6",
        "status":{
           "code":10000,
           "description":"Ok"
        },
        "created_at":"2017-02-14T03:18:54.548733Z",
        "model":{
           "name":"general-v1.3",
           "id":"aaa03c23b3724a16a56b629203edc62c",
           "created_at":"2016-03-09T17:11:39.608845Z",
           "app_id":null,
           "output_info":{
              "message":"Show output_info with: GET \/models\/{model_id}\/output_info",
              "type":"concept"
           },
           "model_version":{
              "id":"aa9ca48295b37401f8af92ad1af0d91d",
              "created_at":"2016-07-13T01:19:12.147644Z",
              "status":{
                 "code":21100,
                 "description":"Model trained successfully"
              }
           }
        },
        "input":{
           "id":"db1b183a95a042d3bd873f8ca69ae2e6",
           "data":{
              "image":{
                 "url":"https:\/\/samples.clarifai.com\/metro-north.jpg"
              }
           }
        },
        "data":{
           "concepts":[
              {
                 "id":"ai_HLmqFqBf",
                 "name":"\u043f\u043e\u0435\u0437\u0434",
                 "app_id":null,
                 "value":0.9989112
              },
              // and several others
              {
                 "id":"ai_VSVscs9k",
                 "name":"\u0442\u0435\u0440\u043c\u0438\u043d\u0430\u043b",
                 "app_id":null,
                 "value":0.9230834
              }
           ]
        }
     }
  ]
}

这可以通过图像URL发生

    $modelResult = $clarifai->getModelRepository()->predictPath(
        '/user/images/image.png',
        \DarrynTen\Clarifai\Repository\ModelRepository::GENERAL
    );

或b64编码的数据发生

    $modelResult = $clarifai->getModelRepository()->predictEncoded(
        ENCODED_IMAGE_HASH,
        \DarrynTen\Clarifai\Repository\ModelRepository::GENERAL
    );

文档

这将最终完全模拟网站上可用的文档。 https://developer.clarifai.com/guide

每个部分都必须有一个简短的说明和一些示例代码，就像在API文档页面上的那样。

勾选的项已完成。

  • 输入
    • 添加
    • 带概念添加
    • 带自定义元数据添加
    • 带裁剪添加
    • 获取输入
    • 获取输入状态
    • 更新输入的概念
    • 从输入中删除概念
    • 批量更新输入的概念
    • 批量删除输入列表中的概念
    • 按ID删除输入
    • 删除输入列表
    • 删除所有输入
  • 模型
    • 创建模型
    • 带有概念创建模型
    • 向模型中添加概念
    • 从模型中移除概念
    • 更新模型名称和配置
    • 获取模型
    • 按ID获取模型
    • 按ID获取模型输出信息
    • 列出模型版本
    • 按ID获取模型版本
    • 获取模型训练输入
    • 按版本获取模型训练输入
    • 删除模型
    • 删除模型版本
    • 删除所有模型
    • 训练模型
    • 用模型进行预测
  • 搜索
    • 按名称和类型搜索模型
    • 按预测概念搜索
    • 按用户提供的概念搜索
    • 按自定义元数据搜索
    • 按反向图片搜索
    • 搜索匹配URL
    • 按概念和预测搜索
    • 搜索AND操作
  • 分页
  • 补丁
    • 合并
    • 移除
    • 覆盖
  • 批量请求
  • 语言

输入

该API围绕一个简单的想法构建。您将输入（图像）发送到服务，它返回预测。除了对输入进行预测外，您还可以“保存”输入及其预测以供以后搜索。您还可以“保存”带有概念的输入以供以后训练自己的模型。

添加输入

您可以逐个或批量添加输入。如果您批量发送，则每次最多只能发送128个输入。

图像可以是公开可访问的URL或文件字节。如果您发送文件字节，则必须使用base64编码。

鼓励您发送带有自己的id的输入。这将帮助您以后将输入与自己的数据库匹配。如果您不发送id，系统将为您创建一个。

使用公开可访问的URL添加输入

    $input = new Input();
    $input->setImage('https://samples.clarifai.com/metro-north.jpg')->isUrl();
    $inputResult = $clarifai->getInputRepository()->add($input);

使用图像的本地路径添加输入

    $input = new Input();
    $input->setImage('/samples.clarifai.com/metro-north.jpg')->isPath();
    $inputResult = $clarifai->getInputRepository()->add($input);

使用字节添加输入

数据必须是base64编码。当您将base64图像添加到我们的服务器时，将在我们的服务器上存储并托管其副本。如果您已经有图像托管服务，我们建议您使用它并通过url参数添加图像。

    $input = new Input();
    $input->setImage(ENCODED_IMAGE_HASH)->isEncoded();
    $inputResult = $clarifai->getInputRepository()->add($input);

添加具有id的多个输入

    $input1 = new Input();
    $input1->setImage('https://samples.clarifai.com/metro-north.jpg')->isUrl()->setId('id1');
    $input2 = new Input();
    $input2->setImage('https://samples.clarifai.com/puppy.jpeg')->isUrl()->setId('id2');
    $inputResult = $clarifai->getInputRepository()->add([$input1, $input2]);

添加带有概念的输入

    $concept = new Concept();
    $concept->setId('boscoe')->setValue(true);

    $input = new Input();
    $input->setImage('https://samples.clarifai.com/puppy.jpeg')->isUrl()
        ->setConcepts([$concept]);

    $inputResult = $clarifai->getInputRepository()->add($input);

添加带有元数据的输入

除了添加带有概念的输入外，您还可以添加带有自定义元数据的输入。然后这些元数据将是可搜索的。元数据可以是任何任意JSON。

    $input = new Input();
    $input->setImage('https://samples.clarifai.com/metro-north.jpg')->isUrl()
        ->setMetaData([['key' => 'value', 'list' => [1, 2, 3]]);
    $inputResult = $clarifai->getInputRepository()->add($input);

添加带有裁剪的输入

在添加输入时，您可以指定裁剪点。API将裁剪图像并使用生成的图像。裁剪点是以百分比形式给出的，从左上角开始，顺序为上、左、下和右。

例如，如果您提供裁剪为0.2, 0.4, 0.3, 0.6，这意味着裁剪图像的顶部边缘将从原始顶部边缘向下20%开始，左侧边缘将从原始左侧边缘开始40%，底部边缘将从原始顶部边缘开始30%，右侧边缘将从原始左侧边缘开始60%。

    $input = new Input();
    $input->setImage('https://samples.clarifai.com/metro-north.jpg')->isUrl()
        ->setCrop([0.2, 0.4, 0.3, 0.6]);
    $inputResult = $clarifai->getInputRepository()->add($input);

获取输入

您可以列出您之前添加的所有输入（图像），无论是用于搜索还是训练。

如果您添加了带有概念的输入，它们也会在响应中返回。

此请求已实现，但尚未分页

    $inputResult = $clarifai->getInputRepository()->get();

按ID获取输入

如果您想按ID获取特定的输入，您也可以这样做。

    $inputResult = $clarifai->getInputRepository()->getById('id');

获取输入状态

如果您批量添加输入，它们将在后台处理。您可以像这样获取所有输入的状态（已处理、待处理和错误）

    $inputResult = $clarifai->getInputRepository()->getStatus();

使用概念更新输入

要更新带有新概念的输入或更改概念值从true/false，您可以这样做

    $concept1 = new Concept();
    $concept1->setId('tree')->setValue(true);
    
    $concept2 = new Concept();
    $concept2->setId('water')->setValue(false);

    $modelResult = $clarifai->getInputRepository()->mergeInputConcepts([$inputId => [$concept1, $concept2]]);

从输入中删除概念

要删除已添加到输入中的概念，您可以这样做

    $concept1 = new Concept();
    $concept1->setId('mattid2')->setValue(true);
    
    $concept2 = new Concept();
    $concept2->setId('ferrari')->setValue(false);

    $modelResult = $clarifai->getInputRepository()->deleteInputConcepts([$inputId => [$concept1, $concept2]]);

批量更新输入的概念

您可以使用ID更新现有的输入。如果您想在输入已添加后添加概念，这很有用。

    $concept1 = new Concept();
    $concept1->setId('tree')->setValue(true);
    
    $concept2 = new Concept();
    $concept2->setId('water')->setValue(false);
    
    $concept3 = new Concept();
    $concept3->setId('mattid2')->setValue(true);
    
    $concept4 = new Concept();
    $concept4->setId('ferrari')->setValue(false);

    $modelResult = $clarifai->getInputRepository()->mergeInputConcepts(
        [
            $inputId1 => [$concept1, $concept2],
            $inputId2 => [$concept3, $concept4],
        ]
    );

从输入列表中批量删除概念

您可以从输入列表中批量删除多个概念

    $concept1 = new Concept();
    $concept1->setId('tree')->setValue(true);
    
    $concept2 = new Concept();
    $concept2->setId('water')->setValue(false);
    
    $concept3 = new Concept();
    $concept3->setId('mattid2')->setValue(true);
    
    $concept4 = new Concept();
    $concept4->setId('ferrari')->setValue(false);

    $modelResult = $clarifai->getInputRepository()->deleteInputConcepts(
        [
            $inputId1 => [$concept1, $concept2],
            $inputId2 => [$concept3, $concept4],
        ]
    );

通过ID删除输入

您可以通过ID删除单个输入

    $inputResult = $clarifai->getInputRepository()->deleteById('id');

删除多个输入列表

您还可以在一次API调用中删除多个输入。这将异步执行。

    $inputResult = $clarifai->getInputRepository()->deleteByIdArray(['id1', 'id2']);

删除所有输入

如果您想从应用程序中删除所有输入，您也可以这样做。这将异步执行。

    $inputResult = $clarifai->getInputRepository()->deleteAll();

模型

有许多方法可以处理模型。

创建模型

您可以使用自己的图像和概念创建自己的模型，并对其进行训练。一旦您将其训练成您想要的方式，您就可以使用该模型进行预测。

创建模型时，您需要为其提供一个名称和一个ID。如果您不提供ID，系统将为您创建一个。所有模型都必须具有唯一的ID。

    $model = new Model();
    $model->setId('petsID');
    $modelResult = $clarifai->getModelRepository()->create($model);

通过概念创建模型

您还可以创建一个模型，并使用它将包含的概念初始化。您以后可以随时添加和删除概念。

    $concept = new Concept();
    $concept->setId('boscoe');

    $model= new Model();
    $model->setId('petsId')
        ->setConcepts([$concept])
        ->setConceptsMutuallyExclusive(false)
        ->setClosedEnvironment(false);

    $modelResult = $clarifai->getModelRepository()->create($model);

向模型添加概念

您可以在任何时间向模型添加概念。当您向输入添加概念时，您可能还想将它们添加到模型中。

    $concept = new Concept();
    $concept->setId('dogs');

    $modelResult = $clarifai->getModelRepository()->mergeModelConcepts([$modelId => [$concept]]);

从模型中删除概念

相反，如果您想从模型中删除概念，您也可以这样做。

    $concept = new Concept();
    $concept->setId('dogs');

    $modelResult = $clarifai->getModelRepository()->deleteModelConcepts([$modelId => [$concept]]);

更新模型名称和配置

在此，我们将模型名称更改为'newname'，并将模型配置为具有concepts_mutually_exclusive=true和closed_environment=true。

    $model->setName('newname')
        ->setClosedEnvironment(true)
        ->setConceptsMutuallyExclusive(true);

    $modelResult = $clarifai->getModelRepository()->update($model);

获取模型

获取所有模型列表，包括您创建的模型以及公共模型

    $modelResult = $clarifai->getModelRepository()->get();

通过ID获取模型

所有模型都有唯一的ID。您可以通过ID获取特定模型

    $modelResult = $clarifai->getModelRepository()->getById($modelId);

通过ID获取模型输出信息

模型的输出信息列出了它包含的概念。

    $modelResult = $clarifai->getModelRepository()->getOutputInfoById($modelId);

列出模型版本

每次训练模型时，它都会创建一个新的版本。您可以列出创建的所有版本。

    $modelResult = $clarifai->getModelRepository()->getModelVersions($modelId);

通过ID获取模型版本

要获取特定的模型版本，您必须提供modelId以及versionId。您可以检查模型版本状态，以确定模型是否已训练或仍在训练中。

    $modelResult = $clarifai->getModelRepository()->getModelVersionById($modelId, $versionId);

获取模型训练输入

您可以列出用于训练模型的全部输入。

    $modelResult = $clarifai->getModelRepository()->getTrainingInputsById($modelId);

通过版本获取模型训练输入

您还可以列出用于训练特定模型版本的全部输入。

    $modelResult = $clarifai->getModelRepository()->getTrainingInputsByVersion($modelId, $versionId);

删除模型

您可以使用modelId删除模型。

    $modelResult = $clarifai->getModelRepository()->deleteById($modelId);

删除模型版本

您还可以使用modelId和versionId删除模型的特定版本。

    $modelResult = $clarifai->getModelRepository()->deleteVersionById($modelId, $versionId);

删除所有模型

如果您想删除与应用程序关联的所有模型，您也可以这样做。请谨慎操作，因为这些无法恢复。

    $modelResult = $clarifai->getModelRepository()->deleteAll();

训练模型

当您训练模型时，您是在告诉系统查看您提供的所有带概念的图像并从中学习。此训练操作是异步的。您的模型可能需要几秒钟才能完全训练并准备就绪。

注意：您可以根据需要重复此操作。通过添加更多带概念的图像进行训练，您可以使模型精确地预测您想要的方式。

    $modelResult = $clarifai->getModelRepository()->train($id);

按名称和模型类型搜索模型

您可以通过模型名称和模型类型搜索所有模型。

    $modelResult = $clarifai->getSearchModelRepository()->searchByNameAndType($modelName, 'concept');

搜索

按预测概念搜索

当您添加输入时，它会自动从通用模型中获取预测。您可以搜索这些预测。

    $concept1 = new Concept();
    $concept1->setName('dog')->setValue(true);
    
    $concept2 = new Concept();
    $concept2->setName('cat');
        
    $inputResult = $clarifai->getSearchInputRepository()->searchByPredictedConcepts([$concept1, $concept2]);

按用户提供的概念搜索

在您添加了带概念输入之后，您可以按这些概念进行搜索。

    $concept1 = new Concept();
    $concept1->setName('dog');
    
    $concept2 = new Concept();
    $concept2->setName('cat');
        
    $inputResult = $clarifai->getSearchInputRepository()->searchByUserSuppliedConcepts([$concept1, $concept2]);

按自定义元数据搜索

在您添加了带自定义元数据的输入之后，您可以按该元数据进行搜索。

    $metadata = ['key'=> 'value'];

    $inputResult = $clarifai->getSearchInputRepository()->searchByCustomMetadata([$metadata]);

按反向图像搜索

您可以使用图片在您的收藏中进行反向图像搜索。API 将根据搜索结果与您提供的查询图片的相似度进行排名。

    $input = new Input();
    $input->setImage('https://samples.clarifai.com/metro-north.jpg');
        
    $inputResult = $clarifai->getSearchInputRepository()->searchByReversedImage([$input]);

搜索匹配URL

您也可以通过URL进行搜索。

    $input = new Input();
    $input->setImage('https://samples.clarifai.com/metro-north.jpg');
        
    $inputResult = $clarifai->getSearchInputRepository()->searchByMatchUrl([$input]);

按概念和预测进行搜索

您可以将搜索与您提供的概念以及模型预测的结果结合起来。

    $concept1 = new Concept();
    $concept1->setName('dog');
    
    $concept2 = new Concept();
    $concept2->setName('cat');
        
    $inputResult = $clarifai->getSearchInputRepository()->search(
        [
            \DarrynTen\Clarifai\Repository\SearchInputRepository::INPUT_CONCEPTS => [$concept1],
            \DarrynTen\Clarifai\Repository\SearchInputRepository::OUTPUT_CONCEPTS => [$concept2]
        ]
    );

搜索AND操作

您也可以使用AND进行搜索的组合。

    $concept1 = new Concept();
    $concept1->setName('dog');
    
    $concept2 = new Concept();
    $concept2->setName('cat');
    
    $input = new Input();
    $input->setImage('https://samples.clarifai.com/metro-north.jpg');
    
    $metadata = ['key' => 'value'];
        
    $inputResult = $clarifai->getSearchInputRepository()->search(
        [
            SearchInputRepository::INPUT_CONCEPTS => [$concept1],
            SearchInputRepository::OUTPUT_CONCEPTS => [$concept2],
            SearchInputRepository::IMAGE => [$input],
            SearchInputRepository::METADATA => [$metadata],
        ]
    );

路线图

  • 训练
    • 添加带概念的图片
    • 创建模型
    • 训练模型
    • 使用模型进行预测
  • 搜索
    • 将图片添加到搜索
    • 按概念搜索
    • 反向图像搜索
  • 应用
  • 语言

公共模型ID

  • 通用 - aaa03c23b3724a16a56b629203edc62c
  • 食物 - bd367be194cf45149e75f01d59f77ba7
  • 旅行 - eee28c313d69466f836ab83287a54ed9
  • 成人内容 - e9576d86d2004ed1a38ba0cf39ecb4b1
  • 婚礼 - c386b7a870114f4a87477c0824499348
  • 颜色 - eeed0b6733a644cea07cf4c60f87ebb7
  • 人脸检测 - a403429f2ddf4b49b307e318f00e528b
  • 服装 - e0be3b9d6a454f0493ac3a30784001ff
  • 名人 - e466caa0619f444ab97497640cefc4dc

支持的图片格式

  • JPEG
  • PNG
  • TIFF
  • BMP

缓存

因为这些调用（时间和金钱）很昂贵，其中一些可以通过缓存来受益。所有缓存默认都应关闭，并且仅在显式设置时使用。

这些通过 darrynten/any-cache 包运行，不需要额外的配置。请确保任何包含缓存的特性都是可选的，并且初始设置为 false，以避免意外行为。

贡献和测试

该项目目前有100%的测试覆盖率，请在贡献时确保更新测试。更多信息请参阅 CONTRIBUTING.md。

我们很乐意得到关于制作良好文档的帮助，如果您有任何想法，请与我们联系。

致谢