Orbis快速入门

Orbis是一个通用的框架，用于进行命名实体识别（NEL）评估分析。它支持标准指标，如精确率、召回率和F1分数，并在注释文档的上下文中可视化黄金标准和注释者的结果。对实体进行着色编码，使专家能够快速识别正确和错误的注释以及Orbis提供的对应知识库链接。由于Orbis使用模块化管道架构，因此可以轻松修改、替换或添加评估过程中的不同阶段。

我们的第一次基于Orbis的钻取分析努力的成果在维也纳的SEMANTiCS 2018会议上展出 Odoni, Kuntschik, Braşoveanu, & Weichselbraun, 2018。

先决条件

为了开发和运行Orbis，您需要在您的系统上安装和配置以下内容

• Python 3.7
• Python设置工具
• Linux或Mac OS（Windows未测试）

安装

要使用Orbis，请从PyPI下载并安装它

    $ python3 -m pip install -U orbis-eval['all'] --user

可用的额外选项更多，但我们建议您使用全部选项。只有当您确实知道自己在做什么时才使用其他选项。

    - all: Install all extras for Orbis. Recommended option
    - all_plugins: Install only all plugins for Orbis.
    - all_addons: Install only all addons for Orbis.
    - aggregation: Install only all aggregation plugins for Orbis.
    - evaluation: Install only all evaluation plugins for Orbis.
    - metrics: Install only all metrics plugins for Orbis.
    - scoring: Install only all scoring plugins for Orbis.
    - storage: Install only all storage plugins for Orbis.
    - "plugin or addon name": Install only the specified addon or plugin named.

或者，您可以通过克隆Repo并手动安装Orbis来安装Orbis。插件和扩展必须单独安装。

    $ git clone https://github.com/orbis-eval/Orbis.git
    $ cd Orbis
    $ python3 setup.py install --user
    # or
    $ python setup.py install --user

根据您的系统和是否已安装Python 2和Python 3，您可能需要使用python3（如Ubuntu上所示）或者可能只需python。

测试运行

为了获得Orbis的第一印象并设置用户文件夹，请运行orbis-eval -t。您将需要设置一个Orbis用户文件夹。此文件夹将包含评估运行队列、日志、语料库和monocle数据、输出和文档。默认位置将在用户主目录中的~/orbis-eval。可以指定一个替代位置。

运行orbis-eval -t将在~/orbis-eval/queue/tests中运行测试文件。这些测试配置是为不同的注释者（AIDA、Babelfly、Recognyze和Spotlight）的不同简短评估运行。可以从这些YAML文件中仅取一个作为模板，将它们复制到文件夹~/orbis-eval/queue/activated，并根据您的需要进行修改。

测试运行的HTML结果可以在您的用户Orbis文件夹中找到，例如~/orbis-eval/output/html_pages

Orbis插件

要运行Orbis插件，Orbis提供了一个可以通过运行orbis-addons或orbis-eval --run-addon访问的CLI。菜单将引导您访问插件，插件通常有自己的菜单。

运行

安装后，可以通过运行orbis-eval来执行Orbis。可以通过使用-h（orbis-eval -h）来调用Orbis的帮助。运行orbis-eval将执行文件夹~/orbis-eval/queue/activated中的所有yaml配置文件。在您可以运行评估之前，请使用repoman插件orbis-addons安装yaml配置文件中引用的语料库。

配置评估运行

Orbis使用yaml文件来配置评估运行。这些配置文件位于Orbis用户目录中的队列文件夹~/orbis-eval/queue/activated。

YAML配置文件分为管道的各个阶段

  aggregation:
    service:
      name: aida
      location: web
    input:
      data_set:
        name: rss1
      lenses:
        - 3.5-entity_list_en.txt-14dec-0130pm
      mappings:
        - redirects-v2.json-15dec-1121am
      filters:
        - us_states_list_en-txt-12_jan_28-0913am

  evaluation:
    name: binary_classification_evaluation

  scoring:
    name: nel_scorer
    condition: overlap
    entities:
      - Person
      - Organization
      - Place
    ignore_empty: False

  metrics:
    name: binary_classification_metrics

  storage:
    - cache_webservice_results

聚合

Orbis的聚合阶段收集评估运行所需的所有数据。这包括语料库、查询注释者和映射、monocle使用的透镜和过滤器。聚合设置指定应使用哪些服务、数据集以及哪些透镜、映射和过滤器。

    aggregation:
      service:
        name: aida
        location: web
      input:
        data_set:
          name: rss1
        lenses:
          - 3.5-entity_list_en.txt-14dec-0130pm
        mappings:
          - redirects-v2.json-15dec-1121am
        filters:
          - us_states_list_en-txt-12_jan_28-0913am

yaml配置中的服务部分指定了网络服务的名称（注释服务）。这应该与webservice插件相同（书写相同），但去掉orbis_plugin_aggregation_前缀。

位置指定了注释应该来自哪里。如果设置为web，则聚合插件将尝试查询网络服务。如果位置设置为local，则将使用本地缓存（位于~/orbis-eval/data/corpora/{corpus_name}/copmuted/{annotator_name}/），前提是存在可用的缓存。如果没有缓存，以网络模式运行评估，并将- cache_webservice_results添加到存储部分以构建缓存。

    aggregation:
      service:
        name: aida
        location: web

输入部分定义了应使用哪个语料库（在示例中为rss1）。语料库名称应与位于~/orbis-eval/data/corpora/的语料库文件夹中的名称相同。Orbis将自动从那里找到语料库文本和金标准。

    input:
      data_set:
        name: rss1
      lenses:
        - 3.5 -entity_list_en.txt-14dec-0130pm
      mappings:
        - redirects-v2.json-15dec-1121am
      filters:
        - us_states_list_en-txt-12_jan_28-0913am

如果需要，也可以在输入部分指定透镜、映射和过滤器。这些应位于~/orbis-eval/data/[filters|lenses|mappings]，并在不带文件扩展名的部分中指定。

评估

评估阶段将注释者结果与黄金标准进行比较。评估部分定义了应使用哪种评估方式。评估器应与评估插件的名称相同，但要去掉前缀 orbis_plugin_evaluation_。

    evaluation:
      name: binary_classification_evaluation

评分

评分阶段根据指定条件对评估进行评分。这些条件在评分器中预设，也可以在评分部分指定，以及应评分的实体类型。如果没有定义实体类型，则所有类型都会评分。如果定义了一个或多个实体类型，则仅对这些类型进行评分。此外，可以将 ignore_empty 设置为定义评分器是否应忽略空注释结果。评分器应与评分插件的名称相同，但要去掉前缀 orbis_plugin_scoring_。

    scoring:
      name: nel_scorer
      condition: overlap
      entities:
        - Person
        - Organization
        - Place
      ignore_empty: False

目前可用的条件有

  - simple:
    - same url
    - same entity type
    - same surface form

  - strict:
    - same url
    - same entity type
    - same surface form
    - same start
    - same end

  - overlap:
    - same url
    - same entity type
    - overlap

指标

指标阶段计算用于分析评估的指标。指标应与指标插件的名称相同，但要去掉前缀 orbis_plugin_metrics_。

    metrics:
      name: binary_classification_metrics

存储

存储阶段定义Orbis应创建哪种类型的输出。始终如一，存储应与存储插件的名称相同，但要去掉前缀 orbis_plugin_storage_。

    storage:
      - cache_webservice_results
      - csv_result_list
      - html_pages

可以选择多个存储选项，上述示例中的选项是推荐的（目前可行的）可能性。

可以直接通过在orbis-addon命令后附加插件名称来调用Orbis插件：orbis-addon repoman

数据集

对于NER/NEL任务，评估数据集需要以NIF格式。如果不是这种情况，请自由使用以下转换包

• nifconverter - Python
• pynif - Python
• NIF-lib - Java - 原始NIF库

本地开发（Pycharm）

1. 创建一个新的项目文件夹。

   mkdir Orbis
   

2. 在新创建的文件夹中克隆orbis-eval。

   cd Orbis
   git clone https://github.com/orbis-eval/orbis_eval.git
   

3. 在Pycharm中将orbis-eval作为新项目打开 文件->打开

4. 执行脚本clone_plugins.sh

   cd orbis_eval
   ./clone_plugins.sh
   

5. 将所有下载的插件/插件附加到Pycharm中的项目 文件->打开

6. 对于orbis-eval运行配置文件中的每个附加插件/插件
   • 将存储库克隆到步骤1中创建的文件夹中。
   • 将项目附加到您的orbis-eval项目。
7. 在Pycharm中，转到文件->设置->项目依赖。将所有插件/插件选择为orbis-eval的依赖项。对于每个插件/插件，选择orbis-eval作为依赖项。

8. 在Pycharm中，转到文件->设置->项目解释器。在步骤1中创建的项目文件夹内创建一个新的Python解释器（您也可以使用现有的解释器）。使解释器对所有项目可用。请确保所有项目都使用这个新创建的解释器。

9. 安装orbis-eval和附加插件/插件的全部依赖项（每个项目都包含一个包含所有依赖项的requirements.txt文件）。

10. 添加一个指向orbis-eval主文件的Pycharm运行配置（orbis-eval/orbis-eval/main.py）。
11. 如果需要，运行repoman以创建您的黄金文档（Pycharm运行配置：orbis-eval/orbis-eval/interfaces/addons/main.py）。注意：如果您还没有黄金文档，您也可以使用位于queue/tests中的示例文件来检查您的安装是否正常工作（使用步骤10中创建的运行配置，使用-t作为参数）

12. 使用步骤10中创建的运行配置运行orbis-eval。注意：第一次执行将在您选择的位置创建一个orbis-eval文件夹。该文件夹包含运行评估所需的所有文件。在orbis-eval/queue/中创建一个名为"activated"的文件夹。在这个文件夹中创建一个配置文件。