AIワーカ実装のためのAPIの説明

1. AIワーカの動作概要

AIワーカは，AIワーカ開発者が用意するCrowd4U外の任意のPC上で動作し，Crowd4Uが提供するタスクの作業を行ない，結果を登録します．
AIワーカを実装するには，こちらで用意するPythonライブラリをダウンロードし，サンプルを書き換える方法と，APIを直接利用して自分で開発する方法がありますが，前者をおすすめします．
こちらで用意するPythonライブラリには，各APIを呼び出すためのラッパーが関数として用意されています．
AIワーカが呼び出すAPI (Pythonライブラリのラッパー関数も同様)は，次の3つのグループに分かれます．
- 初期化：AIワーカがタスクを行なうクラウドソーシングプロジェクトとの通信の準備をします．
- AIワーカを開発・AIワーカが学習するための情報入手：タスク一覧やこれまでのタスク結果を入手したり，特定のタスクの結果を求めることができます．
- 実際にタスクを行なう：Crowd4Uからタスクを入手し，AIワーカがアルゴリズムで求めたそのタスクの結果をCrowd4Uに送信します．
Pythonコードのテンプレートの利用方法を 2節で説明します．Native APIの利用方法は今後掲載します．
このドキュメントの内容は今後変更される可能性があります．その場合は，本ページに記載すると共に，登録されたAIワーカのメールアドレスに連絡します．

2. Pythonライブラリ(APIラッパー関数)による AIワーカの開発 (Version 20170912β)

PythonライブラリのAPIラッパー関数について説明します

実行環境とPythonライブラリの入手方法

開発者のPCに最新のPython実行環境が必要です．
コードはgithubから入手してください．最新の情報もそちらにありますので，参照してください．
https://github.com/crowd4u/crowd4py

グループ1: 初期化 - AIワーカがクラウドソーシングプロジェクトと通信する準備を行なう

API: AIワーカとクラウドソーシングプロジェクトの間を接続する

crowd4pyクラスのクラスメソッドです

crowd4py.API(プロジェクト名，結果を格納するリレーション名)

どのクラウドソーシングプロジェクトのどのタスクを行うのかを設定します．最初に一度だけ呼び出します．
引数：プロジェクト名，結果を格納するリレーション名（これらは，AIワーカの申請の許可の連絡と同時に，お教えします．）
返り値：apiオブジェクト

作成したapiオブジェクトをハンドラーとして，タスクを取得，送信を行う

from __init__ import API_CONF, PROJECT_CONF
import crowd4py
api = crowd4py.API(api_info=API_CONF, project_info=PROJECT_CONF)

API_CONF,とPROJECT_CONFは，以下の __init__.pyと同じディレクトリ配下にconfig.iniを追加することで自動的に生成され読み込まれます

config.iniの内約はAIワーカーとうして登録した時に此方からお送りします．

__init__.py

# -*- coding: utf-8 -*-
import configparser
import os

cfg_file = os.path.join(os.path.dirname(__file__), 'config.ini')
config = configparser.ConfigParser()
config.read(cfg_file)
API_CONF = config['crowd4u']
PROJECT_CONF = config['project']

config.ini

# -*- coding: utf-8 -*-

[crowd4u]
API_ROOT = https://crowd4u.org/
REQUESTER = 000
GROUP_ID  = 00
USER_TOKEN = 00000000000000000000
[project]
ID = 000
PROJECT_NAME = project_name
RELATION_NAME = relation_name

グループ2: AIワーカを開発・AIワーカが学習するのためのデータを取得する

get_relation_data: 呼ばれた時点までに行われたタスクとその結果を返す

目的：AIワーカを作成するための教師データを得る
引数：プロジェクト名（optional), リレーション名（optional）
返り値：タスクとその結果が格納されたjson

Classメソッドから呼び出す場合は引数を指定する必要がある

>>> import crowd4py
>>> crowd4py.API.get_relation_data(project_name="competetion_phase1", relation_name="Results")
{"tid":"1354.1356","task_instance_id":1,"group_id":182,"master_bib_id":"Kyoto_Pref_Kpla-100769607",
"title_1":"建設部門延長産業連関表","volume_1":"","responsibility_1":"","publisher_name_1":"経済調査会",
"issued_1":"1992.0","isbn_1":"","origin_name_1":"京都学・歴彩館","origin_id_1":"100769607",
"origin_url_1":"http://opacs.pref.kyoto.lg.jp/mylimedio/search/book.do?bibid=540085",
"sub_bib_id":"NDL-R100000002-I000002131701-00","title_2":"東京都産業連関表","volume_2":"昭和60年 計数編",
"responsibility_2":"","publisher_name_2":"東京都総務局統計部統計調査課","issued_2":"1991.0","isbn_2":"",
"origin_name_2":"全国書誌","origin_id_2":"91066336","origin_url_2":"http://iss.ndl.go.jp/books/R100000002-I000002131701-00",
"player_id":"934","is_same":null,"is_skipped":null,"_fact_id":25578}

コネクションを作った場合は，作成時に渡した情報を参照するので引数は必要ない

import crowd4py
from __init__ import API_CONF, PROJECT_CONF

api = crowd4py.API(api_info=API_CONF, project_info=PROJECT_CONF)
json = api.get_relation_data()

request_answer: 指定したタスクの優先順位を上げる

目的：AIワーカを作る時，特に情報が欲しいタスクが優先的に行われるようリクエストできます．
引数：優先順位を上げたいタスクのタスクID
返り値：なし

import crowd4py
from __init__ import API_CONF, PROJECT_CONF

api = crowd4py.API(api_info=API_CONF, project_info=PROJECT_CONF)
api.request_answer(tid="123.456")

グループ3: Crowd4Uよりタスクを入手し，タスク結果をCrowd4Uに送信する

get_task: タスクを要求する

目的：AIワーカが作業を行うために，タスクを要求します
引数：なし
返り値：タスクオブジェクト

import crowd4py
from __init__ import API_CONF, PROJECT_CONF

api = crowd4py.API(api_info=API_CONF, project_info=PROJECT_CONF)
task = api.get_task()

タスクオブジェクトはタスクの情報が辞書型にまとまったものと，タスクを送信する先のurlの文字列をプロパティとして持ちます．

post_answer: タスクの結果をCrowd4Uに渡す

目的：AIワーカがタスクを行った結果を，Crowd4Uに渡します
引数：宛先url，dict型の回答
返り値：なし

import crowd4py
from __init__ import API_CONF, PROJECT_CONF

api = crowd4py.API(api_info=API_CONF, project_info=PROJECT_CONF)
task = api.get_task()
answer_data = task.data.copy() # 辞書型のオブジェクトをコピー
answer_data['is_same'] = True # この例では，is_sameにBool値を入れて解答を行うタイプのタスク
task.data = answer_data
api.post_answer(post_url=task.get_post_url, ans_data=task.data)

サンプルコード

受け取った書籍のタイトルが同じ場合に，同じ書籍とみなす簡単なサンプルになります．

# -*- coding: utf-8 -*-
from __init__ import API_CONF, PROJECT_CONF
import crowd4py


def example_predict(data):
    # 書誌のタイトルが同じなら同じ書誌とみなす
    print("------Received task bellow-------")
    print(data)
    if data['title_1'] == data['title_2']:
        data['is_same'] = True
    else:
        data['is_same'] = False
    return data

if __name__ == '__main__':
    api = crowd4py.API(api_info=API_CONF, project_info=PROJECT_CONF)

    # 5回タスクに回答
    print("------begin to answer-------")
    for i in range(5):
        task = api.get_task(debug=True)
        ans_data = example_predict(task.data)
        api.post_answer(task.post_url, ans_data)