4.4 · 用户与工作空间管理（User and Workspace Management）

用户与工作空间管理（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/argilla-io/argilla/4.4-user-and-workspace-management

翻译时间：2026-05-27T08:44:35.117Z

翻译模型：deepseek-chat

原文字符数：17462

项目：Argilla (argilla)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，将以下 DeepWiki 技术文档全文翻译为中文，并进行润色，使其符合中文技术写作习惯。

---

用户与工作空间管理

相关源文件

本 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/api/handlers/v1/users.py
• argilla-server/src/argilla_server/api/policies/v1/user_policy.py
• argilla-server/src/argilla_server/api/schemas/v1/users.py
• argilla-server/src/argilla_server/api/schemas/v1/workspaces.py
• argilla-server/src/argilla_server/contexts/accounts.py
• argilla-server/tests/unit/api/handlers/v1/users/test_create_user.py
• argilla-server/tests/unit/api/handlers/v1/users/test_update_user.py
• argilla-server/tests/unit/api/handlers/v1/workspaces/test_create_workspace.py
• argilla-v1/src/argilla_v1/_version.py
• argilla/CHANGELOG.md
• argilla/docs/how_to_guides/migrate_from_legacy_datasets.md
• argilla/pdm.lock
• argilla/pyproject.toml
• argilla/src/argilla/__init__.py
• argilla/src/argilla/_api/_workspaces.py
• argilla/src/argilla/_version.py
• argilla/src/argilla/records/_mapping/_mapper.py
• argilla/src/argilla/records/_mapping/_routes.py
• argilla/src/argilla/users/_resource.py
• argilla/src/argilla/v1/__init__.py
• argilla/src/argilla/workspaces/_resource.py
• argilla/tests/integration/test_manage_users.py
• argilla/tests/integration/test_manage_workspaces.py
• argilla/tests/unit/test_record_ingestion.py
• docs/_source/_common/tabs/argilla_install_python.md
• docs/_source/community/contributing.md
• docs/_source/community/developer_docs.md
• docs/_source/community/migration-rubrix.md
• docs/_source/getting_started/installation/deployments/docker.md
• docs/_source/getting_started/installation/deployments/docker_compose.md
• docs/_source/getting_started/installation/deployments/python.md
• docs/_source/reference/cli.md
• docs/_source/reference/notebooks.rst
• docs/migration-rubrix.md
• docs/template.ipynb

本文档介绍如何在 Argilla 中管理用户和工作空间，涵盖用户创建、工作空间分配、认证和基于角色的访问控制。有关数据集访问控制的信息，请参阅创建和管理数据集。

概述

Argilla 通过工作空间实现了多租户架构。工作空间作为隔离环境，可以在其中创建和管理数据集。一个用户可以属于多个工作空间，其对数据集的访问权限由角色和工作空间成员关系共同决定。

graph TD
    subgraph "认证"
        JWT["JWT 令牌"]
        API_Key["API 密钥"]
    end

    subgraph "用户管理"
        User["用户
        - 用户名
        - 名
        - 姓
        - 角色
        - API 密钥"]

        Role["角色：
        - 所有者
        - 管理员
        - 标注员"]

        User --> Role
    end

    subgraph "工作空间管理"
        Workspace["工作空间
        - 名称
        - ID"]

        WorkspaceUser["工作空间用户
        - 用户 ID
        - 工作空间 ID"]

        User <--> WorkspaceUser
        Workspace <--> WorkspaceUser
    end

    subgraph "资源访问"
        Dataset["数据集"]

        Workspace --> Dataset
        User --> JWT
        User --> API_Key
    end

来源：

• argilla-server/src/argilla_server/contexts/accounts.py
• argilla/src/argilla/users/_resource.py
• argilla/src/argilla/workspaces/_resource.py
• argilla/CHANGELOG.md:22-25

用户管理

用户角色与权限

Argilla 支持三种用户角色，每种角色拥有不同的权限：

角色	描述	权限
owner（所有者）	对系统拥有完全控制权	创建/删除用户、工作空间和数据集；在工作空间中添加/移除用户
admin（管理员）	拥有管理能力	创建数据集，管理其工作空间内的数据集
annotator（标注员）	拥有基本的标注能力	对其有访问权限的数据集提交标注

来源：

• argilla-server/src/argilla_server/api/schemas/v1/users.py
• argilla/tests/integration/test_manage_users.py

创建用户

您可以使用 Python SDK 以编程方式创建用户：

import argilla as rg

client = rg.Argilla()

# 创建一个新用户
user = rg.User(
    username="john_doe",
    first_name="John",
    last_name="Doe",
    role="annotator",
    password="secure_password"
)
client.users.add(user)

# 创建一个具有预定义 ID 的用户
import uuid
user_id = uuid.uuid4()
user = rg.User(
    id=user_id,
    username="jane_doe",
    first_name="Jane",
    last_name="Doe",
    role="admin",
    password="secure_password"
)
client.users.add(user)

来源：

• argilla/src/argilla/__init__.py:16-18
• argilla/tests/integration/test_manage_users.py:24-34
• argilla/CHANGELOG.md:22-25

更新用户

可以使用 SDK 更新用户属性：

import argilla as rg

client = rg.Argilla()

# 获取一个现有用户
user = client.users(username="john_doe")

# 更新用户属性
user.first_name = "Johnny"
user.last_name = "Doe Jr."
user.role = "admin"
user.update()

来源：

• argilla/tests/integration/test_manage_users.py:57-72
• argilla/CHANGELOG.md:62

删除用户

可以使用 SDK 删除用户：

import argilla as rg

client = rg.Argilla()

# 获取并删除一个用户
user = client.users(username="john_doe")
user.delete()

来源：

• argilla/tests/integration/test_manage_users.py:41-45

工作空间管理

工作空间是数据集的容器，为不同项目或团队提供隔离。每个数据集只属于一个工作空间。

工作空间结构

classDiagram
    class User {
        +UUID id
        +String username
        +String first_name
        +String last_name
        +String role
        +String api_key
        +DateTime inserted_at
        +DateTime updated_at
    }

    class Workspace {
        +UUID id
        +String name
        +DateTime inserted_at
        +DateTime updated_at
    }

    class WorkspaceUser {
        +UUID workspace_id
        +UUID user_id
    }

    class Dataset {
        +UUID id
        +String name
        +UUID workspace_id
    }

    User "n" -- "m" WorkspaceUser
    Workspace "1" -- "m" WorkspaceUser
    Workspace "1" -- "n" Dataset

来源：

• argilla-server/src/argilla_server/contexts/accounts.py
• argilla/src/argilla/workspaces/_resource.py

创建工作空间

可以以编程方式创建工作空间：

import argilla as rg
import uuid

client = rg.Argilla()

# 创建一个新的工作空间
workspace = rg.Workspace(name="research-team")
client.workspaces.add(workspace)

# 创建一个具有预定义 ID 的工作空间
workspace_id = uuid.uuid4()
workspace = rg.Workspace(id=workspace_id, name="product-team")
client.workspaces.add(workspace)

来源：

• argilla/src/argilla/__init__.py:17
• argilla-server/src/argilla_server/contexts/accounts.py:66-78
• argilla/CHANGELOG.md:22-25

管理工作空间中的用户

可以将用户添加到工作空间或从中移除：

import argilla as rg

client = rg.Argilla()

# 获取一个用户和工作空间
user = client.users(username="john_doe")
workspace = client.workspaces(name="research-team")

# 将用户添加到工作空间
user.add_to_workspace(workspace)

# 检查用户是否在工作空间中
assert user in workspace.users

# 将用户从工作空间中移除
user.remove_from_workspace(workspace)

来源：

• argilla/tests/integration/test_manage_users.py:47-55
• argilla-server/src/argilla_server/contexts/accounts.py:32-48

认证与授权

Argilla 支持通过 JWT（JSON Web 令牌）和 API 密钥进行认证。系统使用 bcrypt 进行安全的密码哈希处理。

认证流程

sequenceDiagram
    participant User
    participant SDK as "Argilla SDK"
    participant Server as "Argilla 服务器"
    participant JWT as "JWT 生成"
    participant DB as "数据库"

    User->>SDK: rg.Argilla(api_key="key")
    SDK->>Server: 使用 API 密钥发起请求
    Server->>DB: 校验 API 密钥
    DB-->>Server: 用户信息
    Server-->>SDK: API 响应
    SDK-->>User: 客户端就绪

    User->>SDK: rg.Argilla(username="user", password="pass")
    SDK->>Server: 使用凭证进行认证
    Server->>DB: 校验凭证
    DB-->>Server: 用户信息
    Server->>JWT: 生成 JWT 令牌
    JWT-->>Server: JWT 令牌
    Server-->>SDK: 返回 JWT 令牌
    SDK-->>User: 客户端就绪（携带令牌）

来源：

• argilla-server/src/argilla_server/contexts/accounts.py:186-219

API 密钥认证

Argilla 中的每个用户都有一个可用于认证的 API 密钥。这对于通过 Python SDK 进行程序化访问特别有用。

import argilla as rg

# 使用 API 密钥进行认证
client = rg.Argilla(api_key="user_api_key")

# 从用户设置中获取您的 API 密钥
user = client.me()
api_key = user.api_key

来源：

• argilla-frontend/translation/en.js:93-96

用户管理界面

Argilla 提供了一个用户界面，用于管理您自己的用户设置和查看 API 密钥：

graph TD
    UserAvatar["用户头像菜单"] --> UserSettings["用户设置页面"]

    subgraph "用户设置页面"
        UserInfo["用户信息
        - 用户名
        - 名
        - 姓"]

        ApiKeySection["API 密钥区域
        - 查看 API 密钥
        - 复制 API 密钥"]

        ThemeSettings["主题设置
        - 系统
        - 浅色
        - 深色
        - 高对比度"]

        LanguageSettings["语言设置
        - 英语
        - 德语
        - 西班牙语
        - 等"]
    end

    UserInfo --> ApiKeySection
    ApiKeySection --> ThemeSettings
    ThemeSettings --> LanguageSettings

来源：

• argilla-frontend/translation/en.js:85-99
• argilla-frontend/translation/de.js:82-96
• argilla-frontend/translation/es.js:79-93

服务端实现

用户和工作空间管理功能在服务端通过一组 API 端点和数据库模型实现：

flowchart TD
    subgraph "API 端点"
        UserEndpoints["用户端点
        - GET /api/v1/me
        - GET /api/v1/users
        - GET /api/v1/users/:user_id
        - POST /api/v1/users
        - DELETE /api/v1/users/:user_id"]

        WorkspaceEndpoints["工作空间端点
        - GET /api/v1/workspaces
        - POST /api/v1/workspaces
        - GET /api/v1/workspaces/:workspace_id/users
        - POST /api/v1/workspaces/:workspace_id/users
        - DELETE /api/v1/workspaces/:workspace_id/users/:user_id"]

        AuthEndpoints["认证端点
        - POST /api/v1/token"]
    end

    subgraph "业务逻辑"
        UserFunctions["用户函数
        - create_user()
        - update_user()
        - delete_user()
        - list_users()
        - get_user_by_username()
        - get_user_by_api_key()"]

        WorkspaceFunctions["工作空间函数
        - create_workspace()
        - delete_workspace()
        - list_workspaces()
        - list_workspaces_by_user_id()"]

        AuthFunctions["认证函数
        - authenticate_user()
        - generate_user_token()
        - hash_password()
        - verify_password()"]
    end

    subgraph "数据库模型"
        UserModel["用户模型
        - id: UUID
        - username: 字符串
        - first_name: 字符串
        - last_name: 字符串
        - role: 枚举
        - password_hash: 字符串
        - api_key: 字符串"]

        WorkspaceModel["工作空间模型
        - id: UUID
        - name: 字符串"]

        WorkspaceUserModel["工作空间用户模型
        - workspace_id: UUID
        - user_id: UUID"]
    end

    UserEndpoints --> UserFunctions
    WorkspaceEndpoints --> WorkspaceFunctions
    AuthEndpoints --> AuthFunctions

    UserFunctions --> UserModel
    WorkspaceFunctions --> WorkspaceModel
    UserFunctions --> WorkspaceUserModel
    WorkspaceFunctions --> WorkspaceUserModel

来源：

• argilla-server/src/argilla_server/contexts/accounts.py
• argilla-server/CHANGELOG.md:207-215

最佳实践与建议

1. 角色分配：为每个用户分配所需的最小权限角色（最小权限原则）。
2. 工作空间组织：根据团队或项目创建工作空间，以维护清晰的访问边界。
3. API 密钥安全：将 API 密钥视为密码对待——不要将其硬编码在脚本中或提交到版本控制系统。
4. 密码安全：使用强密码，并考虑实施密码轮换策略。

结论

正确的用户和工作空间管理对于 Argilla 的安全运行至关重要，尤其是在多用户环境中。通过理解角色、权限以及用户与工作空间之间的关系，您可以为标注项目创建一个安全且组织良好的环境。

来源：

• docs/community/developer_docs.md:318-321
• docs/_source/community/contributing.md