agentic_huge_data_base / wiki
页面 Onyx · 5.1 助手配置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 5.1

5.1 · 助手配置（Assistant Configuration）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节5.1 状态全文译文 模块界面与交互、模型调用与提供方适配、文档对象与元数据、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Assistant Configuration 上一章5 下一章5.2
源码线索
  • backend/ee/onyx/db/persona.py
  • backend/onyx/db/persona.py
  • backend/onyx/server/features/persona/api.py
  • backend/onyx/server/features/persona/models.py
  • backend/onyx/server/features/tool/api.py
  • backend/onyx/server/features/tool/models.py
  • backend/tests/integration/common_utils/managers/persona.py
  • backend/tests/integration/tests/permissions/test_persona_permissions.py
  • backend/tests/unit/onyx/db/test_persona_display_priority.py
  • web/lib/opal/src/layouts/content-action/components.tsx
模块标签
  • 界面与交互
  • 模型调用与提供方适配
  • 文档对象与元数据
  • 测试、发布与运维
  • 接口与服务契约

章节正文

助手配置

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/5.1-assistant-configuration

助手配置

相关源文件

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

  • backend/ee/onyx/db/persona.py
  • backend/onyx/db/persona.py
  • backend/onyx/server/features/persona/api.py
  • backend/onyx/server/features/persona/models.py
  • backend/onyx/server/features/tool/api.py
  • backend/onyx/server/features/tool/models.py
  • backend/tests/integration/common_utils/managers/persona.py
  • backend/tests/integration/tests/permissions/test_persona_permissions.py
  • backend/tests/unit/onyx/db/test_persona_display_priority.py
  • web/lib/opal/src/layouts/content-action/components.tsx
  • web/src/app/craft/layout.tsx
  • web/src/app/craft/onboarding/BuildOnboardingProvider.tsx
  • web/src/app/css/card.css
  • web/src/app/css/general-layouts.css
  • web/src/layouts/general-layouts.tsx
  • web/src/lib/tools/interfaces.ts
  • web/src/refresh-components/cards/Card.tsx
  • web/src/refresh-pages/AgentEditorPage.tsx
  • web/src/refresh-pages/admin/ChatPreferencesPage.tsx
  • web/src/sections/modals/AgentViewerModal.tsx
  • web/src/sections/modals/ShareAgentModal.tsx

本文档记录了 Persona 模型及其配置字段。Persona（在用户界面中称为"助手"或"代理"）是 Onyx 中 AI 行为的核心抽象，封装了提示词、工具、知识源和访问控制。

目的与范围

本文涵盖以下内容：

  • Persona 数据库模型及其技术实现。
  • 身份与生命周期字段（名称、描述、软删除）。
  • 大语言模型（LLM）模型选择逻辑与覆盖设置。
  • 检索配置（搜索起始时间、文档集、层级节点）。
  • 用户和组的访问控制机制。
  • 工具集成，包括 MCP（模型上下文协议）和自定义工具。

Persona 模型概览

Persona 类是一个 SQLAlchemy 模型，代表一个 AI 助手。它是行为（提示词）、能力（工具）和知识（文档集/层级节点）的连接点。

Onyx · Persona 模型概览 · 图 1
Onyx · Persona 模型概览 · 图 1

来源：backend/onyx/db/models.py:1562-1800、backend/onyx/db/persona.py:30-39、backend/onyx/server/features/persona/models.py:106-140

核心配置字段

身份与显示
  • name：助手的显示名称。backend/onyx/db/models.py:1585
  • description：助手用途的简短摘要。backend/onyx/db/models.py:1587
  • icon_name / uploaded_image_id：用于自定义助手的视觉表示。前端 AgentIconEditor 负责将文件上传到 /api/admin/persona/upload-image 并设置这些字段。web/src/refresh-pages/AgentEditorPage.tsx:122-175、backend/onyx/db/models.py:1608-1614
  • display_priority：一个整数，决定在用户界面中的排序顺序。backend/onyx/db/models.py:1605
  • is_featured：一个标志，用于在用户界面中突出显示特定助手。backend/onyx/db/models.py:1602
行为与提示词
  • system_prompt：定义助手身份的核心指令。backend/onyx/db/models.py:1627
  • task_prompt：针对交互的特定指令。backend/onyx/db/models.py:1633
  • datetime_aware：如果为 true，系统会将当前日期和时间注入到提示词中。backend/onyx/db/models.py:1637
大语言模型（LLM）覆盖设置

Persona 可以强制使用特定模型，覆盖用户偏好或系统默认设置。

  • llm_model_version_override：具体的模型字符串（例如 gpt-4o）。backend/onyx/db/models.py:1618
  • llm_model_provider_override：提供商名称（例如 openai）。backend/onyx/db/models.py:1622

来源：backend/onyx/db/models.py:1585-1637、backend/onyx/server/features/persona/models.py:106-140

知识与检索配置

助手通过与索引数据的关系来定义它们可以"看到"哪些数据。

文档集与层级节点
  • document_sets：来自连接器源的文档集合。backend/onyx/db/models.py:1732-1738
  • hierarchy_nodes：将助手限定到特定的文件夹、频道或空间。backend/onyx/db/models.py:1754-1760
  • search_start_time：检索的时间过滤器。backend/onyx/db/models.py:1684-1692
  • user_files：直接文件附件，当向量数据库被禁用时，使用 FileReaderTool 路径而非向量数据库搜索。backend/onyx/server/features/persona/api.py:84-86、backend/onyx/db/models.py:1762-1768
检索数据流

当用户查询助手时，persona_id 过滤器会被提取并传递给搜索引擎。

Onyx · 检索数据流 · 图 2
Onyx · 检索数据流 · 图 2

来源：backend/onyx/db/persona.py:150-161、backend/onyx/server/features/persona/models.py:180-201、backend/onyx/server/features/persona/api.py:78-110

访问控制与权限

Onyx 使用在 backend/onyx/db/persona.py 中管理的多层权限系统。

可见性与过滤
  • 管理员访问：管理员绕过大多数过滤器。backend/onyx/db/persona.py:77-78
  • 公开/列出：is_public 使其可访问；is_listed 决定其是否在展示列表中显示。backend/onyx/db/persona.py:138-140
  • 私有访问：通过 Persona__User（直接）或 Persona__UserGroup（组）管理。backend/onyx/db/persona.py:143-145
  • 管理员拥有权：如果设置了 CURATORS_CANNOT_VIEW_OR_EDIT_NON_OWNED_ASSISTANTS，管理员只能看到自己的助手。backend/onyx/db/persona.py:116-121
用户角色
角色能力
管理员对所有助手具有完全的增删改查（CRUD）权限。
管理员可以管理分配给 UserGroups 的助手。
基础用户可以创建个人助手；使用公开/共享的助手。

来源：backend/onyx/db/persona.py:74-147、web/src/sections/modals/ShareAgentModal.tsx:61-70

工具集成

助手支持三种类型的工具：内置工具、自定义 OpenAPI 工具和 MCP 服务器工具。

  • tools 关系：连接到 Tool 表的连接点。backend/onyx/db/models.py:1745-1751
  • 内置工具：通过 in_code_tool_id 标识（例如 SearchTool、ImageGenerationTool）。backend/onyx/server/features/tool/api.py:64-68
  • 自定义工具：通过 OpenAPI 模式定义并存储在 Tool 表中。backend/onyx/server/features/tool/api.py:91-101
  • MCP 工具：由模型上下文协议（MCP）服务器提供的工具。web/src/lib/tools/interfaces.ts:56-63、web/src/sections/modals/AgentViewerModal.tsx:196-206
Onyx · 工具集成 · 图 3
Onyx · 工具集成 · 图 3

来源：backend/onyx/db/models.py:1745-1751、backend/onyx/server/features/tool/api.py:83-103、web/src/lib/tools/interfaces.ts:20-37

实现细节

创建与更新

backend/onyx/db/persona.py 中的 create_update_persona 函数负责同步关系。前端使用 PersonaUpsertRequest 来打包所有配置字段，包括 starter_messages 和 label_ids。backend/onyx/server/features/persona/models.py:106-140、backend/onyx/db/persona.py:28

软删除

Persona 使用 deleted 标志。backend/onyx/db/models.py:1597-1599。mark_persona_as_deleted 用于将助手从新交互中隐藏，同时保留历史数据。backend/onyx/server/features/persona/api.py:37

来源：backend/onyx/db/persona.py:24-33、backend/onyx/server/features/persona/api.py:113-186、backend/onyx/db/models.py:1562-1800