Python API（中文译文）
原始 DeepWiki 页面：https://deepwiki.com/argilla-io/argilla/7.1-python-api
翻译时间：2026-05-27T08:44:43.388Z
翻译模型：deepseek-chat
原文字符数：22406
项目：Argilla (argilla)
---
Python API
相关源文件
以下文件被用作生成此 Wiki 页面的上下文：
README.mdargilla-frontend/CHANGELOG.mdargilla-frontend/components/features/annotation/container/questions/form/span/EntityLabelSelection.component.vueargilla-frontend/components/features/annotation/settings/Validation.vueargilla-frontend/components/features/dataset-creation/configuration/DatasetConfigurationForm.vueargilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationFieldSelector.vueargilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationLabels.vueargilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationQuestion.vueargilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationRating.vueargilla-frontend/components/features/dataset-creation/configuration/questions/DatasetConfigurationSpan.vueargilla-frontend/package.jsonargilla-frontend/translation/de.jsargilla-frontend/translation/en.jsargilla-frontend/translation/es.jsargilla-frontend/v1/domain/entities/hub/DatasetCreation.test.tsargilla-frontend/v1/domain/entities/hub/QuestionCreation.tsargilla-frontend/v1/domain/entities/hub/Subset.tsargilla-server/CHANGELOG.mdargilla-server/src/argilla_server/_version.pyargilla-v1/src/argilla_v1/_version.pyargilla/CHANGELOG.mdargilla/src/argilla/__init__.pyargilla/src/argilla/_version.pydocs/_source/.readthedocs.yamldocs/_source/_static/images/og-doc.pngdocs/_source/_templates/page.htmldocs/_source/conf.pydocs/_source/getting_started/quickstart.mddocs/_source/reference/python/python_client.rstdocs/_source/reference/python/python_training.rstdocs/_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 的架构及其与服务器组件的交互方式：
graph TD
subgraph "客户端 Python SDK"
Client["rg.Argilla"]
Dataset["rg.Dataset"]
Settings["rg.Settings"]
Fields["rg.Fields
(TextField, ImageField 等)"]
Questions["rg.Questions
(LabelQuestion 等)"]
Records["dataset.records"]
Vectors["dataset.vectors"]
Metadata["dataset.metadata"]
Client --> Dataset
Dataset --> Settings
Settings --> Fields
Settings --> Questions
Dataset --> Records
Dataset --> Vectors
Dataset --> Metadata
end
subgraph "服务器端"
API["REST API"]
DB[(数据库)]
Search["搜索引擎
(Elasticsearch/OpenSearch)"]
API --> DB
API --> Search
end
Client <--> API
来源：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 中创建和使用数据集的典型工作流：
sequenceDiagram
participant User
participant SDK as "Argilla SDK"
participant Server
User->>SDK: 使用 rg.Argilla 初始化客户端
User->>SDK: 定义设置（字段、问题）
User->>SDK: 使用 rg.Dataset 创建数据集
SDK->>Server: POST /api/v1/datasets
Server-->>SDK: 数据集已创建
User->>SDK: 准备记录
User->>SDK: 使用 dataset.records.log() 记录记录
SDK->>Server: POST /api/v1/datasets/{id}/records/bulk
Server-->>SDK: 记录已添加
User->>SDK: 使用 dataset.add_vector_settings() 添加向量设置
SDK->>Server: POST /api/v1/datasets/{id}/vectors-settings
Server-->>SDK: 向量设置已添加
User->>SDK: 使用 dataset.add_metadata_property() 添加元数据属性
SDK->>Server: POST /api/v1/datasets/{id}/metadata-properties
Server-->>SDK: 元数据属性已添加
User->>SDK: 使用 dataset.records.search() 搜索记录
SDK->>Server: POST /api/v1/datasets/{id}/records/search
Server-->>SDK: 返回匹配的记录
User->>SDK: 使用 dataset.to_datasets() 或 dataset.to_hub() 导出数据
SDK->>Server: GET /api/v1/datasets/{id}/records
Server-->>SDK: 返回所有记录及其响应
来源：argilla/src/argilla/clients.py, argilla/src/argilla/datasets.py, argilla/CHANGELOG.md:116-138
支持的字段类型
Argilla 支持多种字段类型，用于显示不同类型的数据：
| 字段类型 | 描述 | 添加版本 |
|---|---|---|
TextField | 用于显示文本数据 | 核心 |
ImageField | 用于显示图像（URL 和数据 URL） | 2.1.0 |
ChatField | 用于显示聊天对话 | 2.2.0 |
CustomField | 用于使用 HTML/CSS/JS 进行自定义渲染 | 2.3.0 |
来源：argilla/CHANGELOG.md:112-114, argilla/CHANGELOG.md:123-124, argilla/CHANGELOG.md:75-76
支持的问题类型
Argilla 支持不同类型的问题用于标注：
| 问题类型 | 描述 |
|---|---|
LabelQuestion | 用于单标签分类 |
MultiLabelQuestion | 用于多标签分类 |
RatingQuestion | 用于数值评分（自 v1.29.0 起支持 0） |
RankingQuestion | 用于对多个选项进行排序 |
TextQuestion | 用于自由文本响应 |
SpanQuestion | 用于高亮文本片段（自 v1.26.0 起添加） |
来源：argilla/CHANGELOG.md:244-246, argilla/CHANGELOG.md:180-183, argilla-frontend/v1/domain/entities/hub/QuestionCreation.ts:19-26
核心数据模型
下图展示了 Argilla 的核心数据模型，显示了 Python API 中主要类之间的关系：
classDiagram
class Argilla {
+api_url: string
+api_key: string
+__init__(api_url, api_key)
}
class Dataset {
+name: string
+workspace: string
+settings: Settings
+create()
+update()
+delete()
+to_hub()
}
class Settings {
+fields: List[Field]
+questions: List[Question]
+metadata: List[MetadataProperty]
+vectors: List[VectorSettings]
+guidelines: string
+task_distribution: TaskDistribution
}
class Field {
<<abstract>>
+name: string
+title: string
+required: boolean
}
class TextField {
+use_markdown: boolean
}
class ImageField {
}
class ChatField {
}
class CustomField {
}
class Question {
<<abstract>>
+name: string
+title: string
+required: boolean
}
class LabelQuestion {
+labels: List[string]
}
class MultiLabelQuestion {
+labels: List[string]
+options_order: List[string]
}
class RatingQuestion {
+values: List[int]
}
class RankingQuestion {
+values: List[string]
}
class TextQuestion {
}
class SpanQuestion {
+labels: List[string]
+field: string
+allow_overlapping: boolean
}
class Record {
+id: UUID
+fields: Map
+metadata: Map
+vectors: Map
+responses: List[Response]
+suggestions: List[Suggestion]
}
class Response {
+question_name: string
+value: any
+user_id: UUID
+status: ResponseStatus
}
class Suggestion {
+question_name: string
+value: any
+score: float
+agent: string
}
class MetadataProperty {
+name: string
+type: string
+title: string
+visible_for_annotators: boolean
}
class VectorSettings {
+name: string
+dimension: int
}
class TaskDistribution {
+min_submitted: int
}
Argilla --> Dataset
Dataset "1" *-- "1" Settings
Dataset "1" *-- "*" Record
Settings "1" *-- "*" Field
Settings "1" *-- "*" Question
Settings "1" *-- "*" MetadataProperty
Settings "1" *-- "*" VectorSettings
Settings "1" *-- "1" TaskDistribution
Record "1" *-- "*" Response
Record "1" *-- "*" Suggestion
Field <|-- TextField
Field <|-- ImageField
Field <|-- ChatField
Field <|-- CustomField
Question <|-- LabelQuestion
Question <|-- MultiLabelQuestion
Question <|-- RatingQuestion
Question <|-- RankingQuestion
Question <|-- TextQuestion
Question <|-- SpanQuestion
来源：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 与各种外部库集成，用于不同目的：
| 库 | 用途 |
|---|---|
datasets | 用于从 Hugging Face 数据集导入和导出 |
sentence-transformers | 用于生成嵌入向量以进行相似度搜索 |
textdescriptives | 用于从文本中提取元数据 |
huggingface_hub | 用于将数据集推送到 Hugging Face Hub |
来源：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 正在积极开发中，并频繁更新。一些值得注意的近期变更包括：
- 添加了使用预定义 ID 创建用户和工作区的支持（v2.7.0）
- 在搜索结果中添加了相似度搜索分数（v2.7.0）
- 添加了对
CustomField的支持（v2.3.0） - 添加了用于聊天对话的
ChatField（v2.2.0） - 添加了用于图像显示的
ImageField（v2.1.0） - 添加了深色模式支持（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