5.1 · Assistant 配置（Assistant Configuration）

企业连接器与统一搜索 · 本章是 Onyx DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

模块标签

界面与交互
模型调用与提供方适配
文档对象与元数据
测试、发布与运维
接口与服务契约

中文译文

Assistant 配置（中文译文）

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

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

翻译模型：deepseek-chat

原文字符数：10180

项目：Onyx (onyx)

---

助手配置

目的与范围

本文涵盖以下内容：

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

Persona 模型概览

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

erDiagram
    "Persona" ||--o{ "Persona__User" : "分配给"
    "Persona" ||--o{ "Persona__UserGroup" : "组访问"
    "Persona" ||--o{ "DocumentSet" : "引用"
    "Persona" ||--o{ "Tool" : "使用"
    "Persona" ||--o{ "HierarchyNode" : "限定范围"
    "Persona" ||--o| "User" : "拥有者"
    "Persona" ||--o{ "StarterMessage" : "包含"
    "Persona" ||--o{ "UserFile" : "附加文件"

    "Persona" {
        int id PK
        string name
        text description
        string system_prompt
        string task_prompt
        string llm_model_version_override
        string llm_model_provider_override
        bool tools_disabled
        datetime search_start_time
        bool is_public
        bool is_listed
        bool is_featured
        int display_priority
        uuid user_id FK "拥有者"
        bool deleted
        string uploaded_image_id
        string icon_name
    }

    "User" {
        uuid id PK
        string email
        UserRole role
    }

    "Tool" {
        int id PK
        string name
        string in_code_tool_id
        bool enabled
    }

来源：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 过滤器会被提取并传递给搜索引擎。

graph TD
    "用户查询" --> "fetch_persona_by_id"["fetch_persona_by_id"]
    "fetch_persona_by_id" --> "过滤器"["提取 DocumentSet/HierarchyNode ID"]
    "过滤器" --> "SearchTool"["SearchTool 执行"]
    "SearchTool" --> "VespaQuery"["Vespa / OpenSearch 查询"]
    "VespaQuery" --> "LLMContext"["过滤后的上下文片段"]
    "LLMContext" --> "LLMGeneration"["大语言模型（LLM）循环"]

来源：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

graph LR
    "Persona" -- "使用" --> "Tool"
    "Tool" -- "类型" --> "内置"["内置（搜索、Python）"]
    "Tool" -- "类型" --> "自定义"["自定义（OpenAPI）"]
    "Tool" -- "类型" --> "MCP"["MCP 服务器工具"]
    "MCP" -- "属于" --> "MCPServer"["MCPServer 模型"]

来源：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