2.2 · Argilla 服务端（Argilla Server）

Argilla 服务端

Argilla 服务端

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

• 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-server/src/argilla_server/alembic/versions/580a6553186f_add_datasets_users_table.py
• argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py
• argilla-server/src/argilla_server/api/schemas/v1/datasets.py
• argilla-server/src/argilla_server/bulk/records_bulk.py
• argilla-server/src/argilla_server/contexts/datasets.py
• argilla-server/src/argilla_server/database.py
• argilla-server/src/argilla_server/models/database.py
• argilla-server/tests/factories.py
• argilla-server/tests/unit/api/handlers/v1/datasets/records/records_bulk/test_create_dataset_records_bulk.py
• argilla-server/tests/unit/api/handlers/v1/datasets/records/records_bulk/test_dataset_records_bulk_with_responses.py
• argilla-server/tests/unit/api/handlers/v1/datasets/test_get_dataset_progress.py
• argilla-server/tests/unit/api/handlers/v1/responses/test_create_current_user_responses_bulk.py
• argilla-server/tests/unit/api/handlers/v1/test_datasets.py
• argilla-server/tests/unit/api/handlers/v1/test_records.py
• argilla-server/tests/unit/database/models/test_dataset_user_model.py
• argilla-server/tests/unit/test_database.py
• argilla-v1/src/argilla_v1/_version.py
• argilla/CHANGELOG.md
• argilla/src/argilla/__init__.py
• argilla/src/argilla/_version.py

Argilla Server 是 Argilla 平台的服务器端组件，为数据标注工作流提供后端基础设施。它处理来自 SDK 和前端的 API 请求，管理数据库操作，协调搜索功能，并处理后台任务。本文档提供了服务器架构、关键组件和核心功能的技术概述。

有关使用客户端 Python SDK 与服务器交互的信息，请参阅 Argilla SDK。

架构总览

Argilla Server 基于 FastAPI 构建，采用现代 Web 应用架构，具有清晰的层次结构，用于处理请求、执行业务逻辑以及与存储系统交互。

Argilla 服务端组件图

来源：argilla-server/src/argilla_server/database.py、argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py、argilla-server/src/argilla_server/contexts/datasets.py

关键组件

1. Web 层：基于 FastAPI 构建，负责处理 HTTP 请求、路由、认证和响应格式化。
2. 上下文：核心业务逻辑，实现对数据集、记录、响应等对象的操作。
3. 数据库层：使用 SQLAlchemy ORM 提供对数据库（PostgreSQL 或 SQLite）的抽象。
4. 搜索引擎：与 Elasticsearch 或 OpenSearch 交互，提供文本和向量搜索能力。
5. 队列系统：使用 Redis 处理后台作业和异步任务。

数据模型

Argilla Server 的数据模型围绕几个关键实体构建，这些实体代表了数据集、记录、标注和用户管理概念。

核心数据模型图

来源：argilla-server/src/argilla_server/models/database.py

API 结构

Argilla Server 提供 RESTful API，客户端通过该 API 与系统交互。API 具有版本控制，当前版本为 v1。

主要 API 端点

来源：argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py、argilla-server/tests/unit/api/handlers/v1/test_datasets.py

核心功能

数据集管理

数据集是 Argilla 中的核心组织单元。每个数据集包含一个记录集合，这些记录配置了特定的字段、问题、元数据属性和向量设置。

服务器提供以下端点：

• 创建数据集
• 配置数据集设置
• 添加标注字段和问题
• 发布数据集以供标注
• 监控标注进度
• 管理元数据属性和向量设置

数据集创建流程

来源：argilla-server/src/argilla_server/contexts/datasets.py、argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.py

记录管理

记录代表数据集中需要标注的单个数据点。Argilla Server 提供以下强大功能：

• 批量创建记录
• 更新记录字段和元数据
• 搜索和过滤记录
• 跟踪记录状态
• 管理记录向量以进行相似性搜索

记录批量创建流程

来源：argilla-server/src/argilla_server/bulk/records_bulk.py、argilla-server/tests/unit/api/handlers/v1/datasets/records/records_bulk/test_create_dataset_records_bulk.py

标注管理

响应（标注）由用户在标注记录时创建。服务器负责处理：

• 创建和更新响应
• 跟踪响应状态（草稿、已提交、已废弃）
• 计算数据集进度指标
• 按响应状态搜索和过滤记录
• 导出标注

响应创建流程

来源：argilla-server/src/argilla_server/contexts/datasets.py

向量搜索

Argilla Server 通过以下方式支持基于向量的相似性搜索：

• 为数据集配置向量设置
• 存储记录的向量嵌入
• 提供相似性搜索 API 以查找相关记录
• 使用余弦相似度计算对结果进行排序

相似性搜索流程

来源：argilla-server/src/argilla_server/api/handlers/v1/datasets/records/records.py

数据库与存储

Argilla Server 使用多个存储系统来管理数据的不同方面：

数据库

服务器使用 SQLAlchemy ORM 与 PostgreSQL（推荐用于生产环境）或 SQLite（用于开发环境）交互。数据库存储所有持久化实体，包括数据集、记录、字段、问题、响应、用户等。

# 数据库连接设置
async_engine = create_async_engine(settings.database_url, **settings.database_engine_args)
AsyncSessionLocal = async_sessionmaker(autocommit=False, expire_on_commit=False, bind=async_engine)

# 会话处理
async def get_async_db() -> AsyncGenerator[AsyncSession, None]:
    async for db in _get_async_db():
        yield db

来源：argilla-server/src/argilla_server/database.py

搜索引擎

搜索引擎（Elasticsearch 或 OpenSearch）用于：

• 在记录字段中进行文本搜索
• 向量存储和相似性搜索
• 用于指标和过滤的聚合操作

队列系统

Redis 用作队列系统，用于：

• 后台作业处理
• 任务分发
• Webhook 通知投递
• 缓存

API 认证与授权

Argilla Server 使用 API 密钥和基于 JWT 的认证系统来保护 API 端点：

• 每个用户在创建时都会生成一个唯一的 API 密钥
• API 密钥通过 X-Argilla-Api-Key 请求头发送以进行认证
• 基于角色的授权确保用户只能访问允许的资源
• 策略检查每个 API 操作的权限

部署选项

Argilla Server 可以通过多种方式部署：

配置

Argilla Server 通过环境变量进行配置，最重要的配置项包括：

来源：argilla-server/CHANGELOG.md

总结

Argilla Server 提供了强大的后端基础设施，支撑着 Argilla 平台的数据标注能力。通过其 API，它促进了数据集管理、记录存储、标注收集和高级搜索功能，同时处理认证、授权和后台处理需求。

该服务器设计为可扩展、灵活，并且可以在各种环境中部署，从本地开发到大规模生产部署。