Полигон алгоритмов/Взаимодействие с пользовательскими алгоритмами

Материал из MachineLearning.

Версия 20:50, 23 марта 2010

Взаимодействие системы Полигон с внешними алгоритмами осуществляется при помощи веб-сервиса http://poligon.machinelearning.ru/ProcessingService.asmx. Алгоритм должен быть зарегистрирован в системе при помощи мастера добавления алгоритма. Пример подключения алгоритма к системе полигон можно скачать по адресу http://poligon.machinelearning.ru/files/ExampleAlg.rar (C#, Microsoft Visual Studio 2008). Протестировать корректность взаимодействия алгоритма с системой можно при помощи тестового веб-сервиса http://poligon.machinelearning.ru/TestService.asmx. Его интерфейс полностью совпадает с интерфейсом обрабатывающего сервиса.

Общая схема взаимодействия

Связь инициируется пользовательским алгоритмом. Для этого используется функция GetTask.

Если у менеджера алгоритмов классификации есть задание для пользовательского алгоритма, то в результате выполнения функции GetTask алгоритм получит задание на обработку. В задании указаны идентификатор задачи, набор разбиений и параметры запуска алгоритма. Чтобы получить данные задачи классификации алгоритм должен воспользоваться функцией сервиса GetProblem. Получение данных задачи классификации вынесено в отдельную функциональность для оптимизации трафика больших задач классификации – для построения статистики, как правило, требуется обработать несколько заданий. В случае, если в задании указана та же самая задача классификации, алгоритм может не запрашивать ее повторно.

После обработки задания результаты расчетов сохраняются в системе Полигон при помощи функции сервиса RegisterResult.

Функциональность сервиса

Функциональность сервиса составляет 3 функции GetTask(), GetProblem() и RegisterResult(). Ниже приведено описание каждой из этих функций.

Замечания:

• при вызове любой функции сервиса должны быть переданы параметры авторизации – синоним алгоритма и пароль.
• при вызове любой функции частью возвращаемой структуры является тип ProcessingState, отвечающий за состояние обработки запроса.

Тип ProcessingState состоит из полей:

• Status (StatusType) – статус состояния. Описывается структурой enum StatusType {Ok, Warning, Error}. Статус Ok означает, что обработка запроса прошла без ошибок. Статус Warning – обработка прошла с предупреждениями. Error – при обработке произошла ошибка.
• Message (string) – текст ошибки или предупреждения. При статусе Ok равно null.

Получение задания – GetTask()

При помощи этой функции осуществляется проверка наличия у сервера Полигон нового задания на обсчет для пользовательского алгоритма.

[WebMethod(Description = "Взять задание на обсчет.")]
public ProcessingTask GetTask(string algSynonim, string password)

Входные параметры:

• algSynonim (string) – синоним алгоритма (значение должно совпадать со значением, введенным при регистрации алгоритма на сайте).
• passwd (string) – пароль для соединения с системой Полигон. Пароль указывается при регистрации алгоритма и может быть изменен при редактировании карточки алгоритма.

В результате выполнения функции возвращается значение типа ProcessingTask (в случае, если нового задания на обсчет нет, возвращаемое значение будет содержать null).

Тип ProcessingTask состоит из полей:

• PocketId (int) – идентификатор задания. Используется для сопоставления задания и результатов тестирования (см. функцию RegisterResult()).
• LearnIndexes (int[][]) – список индексов объектов для обучения алгоритма. Первый индекс – номер выборки в задании, второй – индекс объекта задачи.
• TestIndexes (int[][]) – список индексов объектов для контроля. Первый индекс – номер выборки в задании, второй – индекс объекта задачи.
• AlgSynonim (string) - синоним алгоритма.
• ProblemSynonim(string) - синоним задачи классификации.
• AlgParamNames (string[]) – список имен передаваемых алгоритму параметров.
• AlgParamValues (string[]) – список значений передаваемых алгоритму параметров.
• AlgParamUsages (bool[]) – список выставленных флагов использования параметров.
• ProcessingState (ProcessingState) – состояние возвращенного задания (была ошибка или нет)

Как правило, эти типы данных создаются автоматически при подключении веб-сервиса в проект.

Получение задачи – GetProblem()

При помощи этой функции осуществляется получение данных задачи классификации, требуемой для обсчета задания.

[WebMethod(Description = "Взять данные задачи по синониму задачи.")]
public ProblemData GetProblem(string algSynonim, string password, string problemSynonim)

Входные параметры:

• algSynonim (string) – синоним алгоритма (значение должно совпадать со значением, введенным при регистрации алгоритма на сайте).
• passwd (string) – пароль для соединения с системой Полигон. Пароль указывается при регистрации алгоритма и может быть изменен при редактировании карточки алгоритма.
• problemSynonim (string) – синоним задачи (значение, указанное в задании на тетсирование).

В результате выполнения функции возвращается значение типа ProblemData. Тип ProblemData состоит из полей:

• DataMatrix (double[][]) – данные задачи. Матрица объекты-признаки.
• Target (int[]) – целевой вектор (вектор классов).
• LossMatrix (double[][]) – матрица потерь. Определяет «стоимость» неправильной классификации. Размерность матрицы – [число классов] х [число классов]. Данное поле является необязательным. Если матрица потерь не задана поле содержит null-значение.
• Weights (double[]) – вектор весов объектов. Необязательный параметр. В настоящий момент не используется при построении статистик.
• PropertiesDescription (PropertyDescription[]) – Описание признаков задачи. Последний признак – целевой (описание допустимых классов). Описание признака состоит из полей:
  • Type (перечисление) – Тип признака. Возможны значения: Nominal (номинальный) и Numerical (числовой);
  • Values (int[]) – значения признака если их конечное число. Параметр актуален ТОЛЬКО для номинальных признаков.
• ProcessingState (ProcessingState) – состояние возвращенного задания (была ошибка или нет)

Как правило, этот тип данных создается автоматически при подключении веб-сервиса в проект.

Сохранение результата – RegisterResult()

При помощи этой функции осуществляется сохранение результатов обсчета задания для тестирования в системе Полигон.

[WebMethod(Description = "Сохранить результат тестирования.")]
public ProcessingState RegisterResult(string algSynonim, string password, int pocketKey, TestResult[] learnResults, TestResult[] testResults)

Параметры:

• algSynonim (string) – синоним алгоритма (значение должно совпадать со значением, введенным при регистрации алгоритма на сайте).
• passwd (string) – пароль для соединения с системой Полигон. Пароль указывается при регистрации алгоритма и может быть изменен при редактировании карточки алгоритма.
• pocketKey (int) – идентификатор задания на тестирование (значение содержится в соответствующем поле ProcessingTask).
• learnResults (TestResult[]) – результат работы алгоритма на обучающих подвыборках (описание типа TestResult приведено ниже). Результаты должны быть записаны в том же порядке, что и в исходной постановке задачи;
• testResults (TestResult[])– результат работы алгоритма на контрольных подвыборках (описание типа TestResult приведено ниже). Результаты должны быть записаны в том же порядке, что и в исходной постановке задачи.

Тип TestResult состоит из полей:

• Index (int) – индекс обучающей подвыборки в исходной постановке задачи. Индексация начинается с нуля. Данное поле является дополнительным параметром контроля правильности проведения тестирования. Его следует заполнять в момент получения результатов теста.
• ProbabilityMatrix (double[][]) – матрица оценок принадлежности объектов классам задачи. Размерность матрицы [количество объектов] x [количество классов]. Все значения должны быть неотрицательными. При сохранении результатов происходит автоматическая нормировка, так чтобы сумма значений строки составляла 1. Если алгоритм не позволяет рассчитывать оценку принадлежности к классу (возвращает класс объекта), то оценка принадлежности объекта этому классу должна быть равна 1 (а остальные оценки нулевыми).
• Answers (int[]) – вектор классификаций объектов. Необязателен, если не указан (null), то вектор классификаций создается по матрице оценок: объекту ставится в соответствие класс с наибольшей оценкой. При равенстве оценок ответ выбирается произвольно из наилучших. Если указан, то должен соответствовать матрице оценок.
• PropertiesWeights (double[]) – необязательный вектор весов признаков. Если алгоритм не строит подобных оценок, значение этого поля должно содержать null. В данный момент не используется.
• ObjectsWeights (double[]) – необязательный вектор весов объектов. Если алгоритм не строит подобных оценок, значение этого поля должно содержать null. В данный момент не используется.
• Error (bool) – признак того, что при обсчете произошла ошибка.
• ErrorException (string) – текст сообщения об ошибке.

Возвращается результат типа ProcessingState, содержащий статус обработки (успешно сохранены данные или нет) и сообщения об ошибках, если они произошли. Как правило, эти типы данных создаются автоматически при подключении веб-сервиса в проект.

Описание тестового сервиса

Тестовый сервис http://poligon.machinelearning.ru/TestService.asmx дублирует функциональность основного обрабатывающего сервиса. При запросе задания алгоритму возвращается стандартное тестовое задание. Для его запроса не требуется регистрация алгоритма на сайте или создание отчета. И, поскольку тестовое задание не изменяется, такой сервис позволяет не только наладить взаимодействие с Системой, но и отладить работу самого алгоритма. Тестовое задание имеет следующий вид: в качестве параметров алгоритма возвращается null, ProblemSynonim равно Iris, указаны индексы разбиений в массивах LearnIndexes и TestIndexes. При запросе задачи (вызове GetProblem) возвращаются данные по задаче Iris. При использовании функции RegisterResults фактически происходит только проверка на корректность. Данные, возвращенные алгоритмом, не сохраняются.