7.1 · Python API

Python API

Python API

相关源文件

本章引用的主要源码文件：

• README.md
• argilla-frontend/CHANGELOG.md
• argilla-frontend/components/features/annotation/container/questions/form/span/EntityLabelSelection.component.vue
• argilla-frontend/components/features/annotation/settings/Validation.vue
• argilla-frontend/components/features/dataset-creation/configuration/DatasetConfigurationForm.vue
• argilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationFieldSelector.vue
• argilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationLabels.vue
• argilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationQuestion.vue
• argilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationRating.vue
• argilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationSpan.vue
• argilla-frontend/package.json
• argilla-frontend/translation/de.js
• argilla-frontend/translation/en.js
• argilla-frontend/translation/es.js
• argilla-frontend/v1/domain/entities/hub/DatasetCreation.test.ts
• argilla-frontend/v1/domain/entities/hub/QuestionCreation.ts
• argilla-frontend/v1/domain/entities/hub/Subset.ts
• argilla-server/CHANGELOG.md
• argilla-server/src/argilla_server/_version.py
• argilla-v1/src/argilla_v1/_version.py
• argilla/CHANGELOG.md
• argilla/src/argilla/__init__.py
• argilla/src/argilla/_version.py
• docs/_source/.readthedocs.yaml
• docs/_source/_static/images/og-doc.png
• docs/_source/_templates/page.html
• docs/_source/conf.py
• docs/_source/getting_started/quickstart.md
• docs/_source/reference/python/python_client.rst
• docs/_source/reference/python/python_training.rst
• docs/_source/requirements.txt

概述

Python API 是以编程方式与 Argilla 交互的主要接口。它使用户能够创建和管理数据集、配置标注任务、添加待标注记录以及导出已标注数据。本文档提供了 Argilla Python SDK 中关键类、方法和模式的全面参考。

有关 Python SDK 交互的 REST API 端点信息，请参阅 REST API。

来源：argilla/README.md:94-108, argilla/src/argilla/__init__.py:1-25

客户端初始化

Argilla Python API 的入口点是 Argilla 类，它通过连接信息初始化客户端以连接到 Argilla 服务器：

import argilla as rg

client = rg.Argilla(api_url="https://[your-owner-name]-[your-space-name].hf.space", api_key="owner.apikey")

你还可以通过 httpx_extra_kwargs 参数传递额外的 HTTP 客户端参数，例如使用 verify=False 禁用 SSL 验证或配置代理。

来源：argilla/README.md:104-108

Python API 架构

下图展示了 Argilla Python SDK 的架构及其与服务器组件的交互方式：

来源：argilla/README.md:94-108, argilla/src/argilla/__init__.py:1-25

数据集

Argilla 中的数据集是待标注数据的容器。每个数据集都有定义其结构的设置，包括字段（显示什么内容）和问题（标注什么内容）。

创建数据集

要创建数据集，你需要定义其设置，然后使用这些设置实例化一个数据集：

settings = rg.Settings(
    guidelines="将评论分类为正面或负面。",
    fields=[
        rg.TextField(
            name="review",
            title="评论文本",
            use_markdown=False,
        ),
    ],
    questions=[
        rg.LabelQuestion(
            name="my_label",
            title="这篇文章属于哪个类别？",
            labels=["positive", "negative"],
        )
    ],
)
dataset = rg.Dataset(
    name="my_first_dataset",
    settings=settings,
    client=client,
)
dataset.create()

来源：argilla/README.md:115-137

数据集创建与使用工作流

下图展示了在 Argilla 中创建和使用数据集的典型工作流：

来源：argilla/src/argilla/clients.py, argilla/src/argilla/datasets.py, argilla/CHANGELOG.md:116-138

支持的字段类型

Argilla 支持多种字段类型，用于显示不同类型的数据：

来源：argilla/CHANGELOG.md:112-114, argilla/CHANGELOG.md:123-124, argilla/CHANGELOG.md:75-76

支持的问题类型

Argilla 支持不同类型的问题用于标注：

来源：argilla/CHANGELOG.md:244-246, argilla/CHANGELOG.md:180-183, argilla-frontend/v1/domain/entities/hub/QuestionCreation.ts:19-26

核心数据模型

下图展示了 Argilla 的核心数据模型，显示了 Python API 中主要类之间的关系：

来源：argilla/CHANGELOG.md:155-165, argilla/CHANGELOG.md:228-229

记录

记录是需要标注的单个数据点。它们可以从各种来源添加到数据集中，包括 Hugging Face 数据集。

添加记录

要将记录添加到数据集：

from datasets import load_dataset

data = load_dataset("imdb", split="train[:100]").to_list()
dataset.records.log(records=data, mapping={"text": "review"})

mapping 参数允许你将数据源中的字段映射到 Argilla 数据集中的字段。

来源：argilla/README.md:147-151, argilla/CHANGELOG.md:116-117

查询记录

可以使用筛选、排序和文本搜索来查询记录：

# 获取所有记录
records = dataset.records.get_all()

# 搜索记录（文本搜索）
records = dataset.records.search(query="text")

# 按元数据筛选记录
records = dataset.records.filter(metadata={"category": "news"})

# 排序记录
records = dataset.records.sort(by="metadata.confidence", order="desc")

# 限制返回的记录数量
records = dataset.records.get_all(limit=100)

自 2.3.0 版本起，你还可以按记录属性（如 id、_server_id、inserted_at 和 updated_at）进行筛选。

来源：argilla/CHANGELOG.md:77-80

向量与相似度搜索

Argilla 支持向记录添加向量嵌入以进行相似度搜索，该功能在 2.3.0 版本中引入：

# 添加向量设置
dataset.add_vector_settings(
    name="embeddings",
    dimension=384,
)

# 向记录添加向量
dataset.records.log(
    records=data,
    vectors={"embeddings": embeddings}
)

# 查找相似记录
similar_records = dataset.find_similar_records(
    record_id="record-123",
    vector_name="embeddings",
    limit=10
)

在计算向量之间的相似度时，相似度搜索默认使用余弦相似度。

来源：argilla/CHANGELOG.md:77-79, argilla/CHANGELOG.md:445-449, argilla/CHANGELOG.md:469

与 Sentence Transformers 集成

自 1.28.0 版本起，Argilla 提供了与 sentence-transformers 的集成，用于生成嵌入向量：

from argilla.client.feedback.integrations.sentence_transformers import SentenceTransformersExtractor

# 创建提取器
extractor = SentenceTransformersExtractor(model_name="all-MiniLM-L6-v2")

# 基于提取器添加向量设置
dataset.add_vector_settings(
    name="embeddings",
    dimension=extractor.dimension,
)

# 提取嵌入向量并添加到记录
records = [{"text": "This is a sample text"}]
records_with_vectors = extractor.extract_vectors(
    records=records,
    vector_name="embeddings",
    fields=["text"]
)
dataset.records.log(records=records_with_vectors)

来源：argilla/CHANGELOG.md:336-337

响应与建议

Argilla 中的标注可以作为响应（人工标注）或建议（预计算标注，通常来自模型）提交。

添加响应

# 添加响应
dataset.records.update(
    records=[
        {
            "id": "record-123",
            "responses": [
                {
                    "question_name": "my_label",
                    "value": "positive"
                }
            ]
        }
    ]
)

添加建议

# 添加建议
dataset.records.update(
    records=[
        {
            "id": "record-123",
            "suggestions": [
                {
                    "question_name": "my_label",
                    "value": "positive",
                    "score": 0.9,
                    "agent": "model-123"
                }
            ]
        }
    ]
)

请注意，自 1.20.0 版本起，agent 字段有字符限制，score 字段必须是 0 到 1 之间的浮点数。

来源：argilla/CHANGELOG.md:413-414

元数据

记录可以关联元数据，用于筛选、组织和附加信息：

# 定义元数据属性
dataset.add_metadata_property(
    name="category",
    type="terms",
    title="Category",
    visible_for_annotators=True
)

# 添加带元数据的记录
dataset.records.log(
    records=data,
    metadata={"category": "news"}
)

自 1.21.0 版本起，Argilla 提供了与 textdescriptives 的集成，用于自动从文本中提取元数据：

from argilla.client.feedback.integrations.textdescriptives import TextDescriptivesExtractor

# 创建提取器
extractor = TextDescriptivesExtractor()

# 提取元数据并添加到记录
records = [{"text": "This is a sample text"}]
records_with_metadata = extractor.extract_metadata(
    records=records,
    fields=["text"]
)
dataset.records.log(records=records_with_metadata)

来源：argilla/CHANGELOG.md:366, argilla/CHANGELOG.md:393

任务分配

自 2.0.0 版本起，Argilla 支持通过 task_distribution 设置配置记录如何分配给标注者：

settings = rg.Settings(
    # 其他设置
    task_distribution=rg.TaskDistribution(
        min_submitted=2  # 每条记录至少需要 2 个响应
    )
)

此参数决定了每条记录在被视为完成之前需要多少个响应。

来源：argilla/CHANGELOG.md:157-158, argilla/CHANGELOG.md:168-169

导出数据

已标注数据可以导出为多种格式，包括 Hugging Face 数据集和 Hugging Face Hub：

# 导出为 HF 数据集
hf_dataset = dataset.to_datasets()

# 导出到 Hugging Face Hub
dataset.to_hub(
    repo_id="username/dataset-name",
    private=True
)

在 2.1.0 版本中，添加了从 Hugging Face Hub 导入数据集时定义数据集设置的支持：

# 从 Hugging Face 导入数据集并自定义设置
dataset = rg.Dataset.from_hub(
    name="my_dataset",
    repo_id="username/dataset-name",
    settings=my_custom_settings  # 可选——否则自动生成
)

来源：argilla/CHANGELOG.md:125-126, argilla/README.md:94-108

与外部库的集成

Argilla 与各种外部库集成，用于不同目的：

来源：argilla/CHANGELOG.md:336-337, argilla/CHANGELOG.md:393

完整示例

以下是一个完整示例，演示了讨论的许多概念：

import argilla as rg
from datasets import load_dataset
from argilla.client.feedback.integrations.sentence_transformers import SentenceTransformersExtractor

# 初始化客户端
client = rg.Argilla(api_url="https://your-argilla-server", api_key="your-api-key")

# 定义设置
settings = rg.Settings(
    guidelines="将评论分类为正面或负面。",
    fields=[
        rg.TextField(
            name="review",
            title="评论文本",
            use_markdown=False,
        ),
    ],
    questions=[
        rg.LabelQuestion(
            name="sentiment",
            title="这条评论的情感是什么？",
            labels=["positive", "negative"],
        )
    ],
    task_distribution=rg.TaskDistribution(min_submitted=1)
)

# 创建数据集
dataset = rg.Dataset(
    name="imdb_sentiment",
    settings=settings,
    client=client,
)
dataset.create()

# 添加元数据属性
dataset.add_metadata_property(
    name="length",
    type="integer",
    title="评论长度",
    visible_for_annotators=True
)

# 创建嵌入向量提取器
extractor = SentenceTransformersExtractor(model_name="all-MiniLM-L6-v2")

# 添加向量设置
dataset.add_vector_settings(
    name="embeddings",
    dimension=extractor.dimension,
)

# 加载数据
data = load_dataset("imdb", split="train[:100]").to_list()

# 提取嵌入向量
data_with_vectors = extractor.extract_vectors(
    records=data,
    vector_name="embeddings",
    fields=["text"]
)

# 添加元数据
for record in data_with_vectors:
    record["metadata"] = {"length": len(record["text"])}

# 写入记录
dataset.records.log(
    records=data_with_vectors,
    mapping={"text": "review"}
)

# 导出到 Hugging Face Hub
dataset.to_hub(
    repo_id="username/imdb_sentiment",
    private=True
)

此示例演示了创建数据集、添加元数据属性和向量设置、从 Hugging Face 加载数据、提取嵌入向量和元数据、写入记录以及导出到 Hugging Face Hub 的完整流程。

来源：argilla/README.md:94-154, argilla/CHANGELOG.md:336-337, argilla/CHANGELOG.md:157-158

在 Hugging Face Spaces 上部署 Argilla

自 2.4.0 版本起，Argilla 提供了一种便捷的方法来在 Hugging Face Spaces 上部署 Argilla 服务器：

import argilla as rg

# 在 Hugging Face Spaces 上部署 Argilla
rg.Argilla.deploy_on_spaces()

这使得为标注项目设置新的 Argilla 服务器变得更加容易。

来源：argilla/CHANGELOG.md:58-59

近期 API 变更

Argilla 正在积极开发中，并频繁更新。一些值得注意的近期变更包括：

1. 添加了使用预定义 ID 创建用户和工作区的支持（v2.7.0）
2. 在搜索结果中添加了相似度搜索分数（v2.7.0）
3. 添加了对 CustomField 的支持（v2.3.0）
4. 添加了用于聊天对话的 ChatField（v2.2.0）
5. 添加了用于图像显示的 ImageField（v2.1.0）
6. 添加了深色模式支持（v2.1.0）

有关完整的变更历史，请参阅仓库中的 CHANGELOG.md 文件。

来源：argilla/CHANGELOG.md:23-26, argilla/CHANGELOG.md:75-76, argilla/CHANGELOG.md:112-114, argilla/CHANGELOG.md:123-124