5 · AI Assistants 与 Personas（AI Assistants and Personas）

AI Assistants 与 Personas（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/5-ai-assistants-and-personas

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

翻译模型：deepseek-chat

原文字符数：9460

项目：Onyx (onyx)

---

AI 助手与角色

相关源文件

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

• 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

目的：本文档记录了 Onyx 中的 AI 助手（角色）系统。该系统允许管理员和用户配置专门的 AI 代理，并为其设置自定义行为、知识来源、工具和模型参数。角色是定制 AI 响应以满足特定用例和用户需求的主要机制。

关于角色在聊天消息处理中的使用方式，请参阅聊天与会话系统。关于大语言模型（LLM）提供商的配置，请参阅大语言模型（LLM）提供商管理。

---

概述

在 Onyx 中，AI 助手（内部称为 Persona）是一个可配置的实体，它定义了大语言模型（LLM）会话的行为逻辑和资源访问权限。它作为 ChatSession 的蓝图，决定了模型的行为方式以及可以访问的数据。

系统包含一个 DEFAULT_PERSONA_ID（通常为 0），代表标准系统行为 backend/onyx/configs/constants.py:21。助手通过前端的 AgentEditorPage web/src/refresh-pages/AgentEditorPage.tsx:104 和后端的 persona 数据库模块 backend/onyx/db/persona.py:30 进行管理。

---

助手配置

Persona 模型代表了数据库中的配置。助手可以通过 PersonaUpsertRequest 进行管理，该请求处理创建和更新操作，包含命名、提示词和工具关联等字段 backend/onyx/server/features/persona/models.py:105-138。

核心配置字段

字段	类型	描述
name	字符串	助手的显示名称 backend/onyx/server/features/persona/models.py:106
description	字符串	向用户展示的高级用途说明 backend/onyx/server/features/persona/models.py:107
system_prompt	字符串	大语言模型（LLM）的核心指令 backend/onyx/server/features/persona/models.py:134
tool_ids	整数列表	工具 ID，如搜索、Python 或图像生成 backend/onyx/server/features/persona/models.py:116
document_set_ids	整数列表	助手可以搜索的知识集 backend/onyx/server/features/persona/models.py:108
default_model_configuration_id	整数	要使用的特定大语言模型（LLM）配置的 ID backend/onyx/server/features/persona/models.py:110
is_public	布尔值	是否所有用户都可以查看/使用此助手 backend/onyx/server/features/persona/models.py:109
display_priority	整数	用于在用户界面中对助手进行排序 backend/onyx/server/features/persona/models.py:125

助手实体关系

erDiagram
    "Persona [onyx.db.models]" ||--o{ "Persona__User [onyx.db.models]" : "shared_with"
    "Persona [onyx.db.models]" ||--o{ "Persona__UserGroup [onyx.db.models]" : "restricted_to"
    "Persona [onyx.db.models]" ||--o{ "Tool [onyx.db.models]" : "equipped_with"
    "Persona [onyx.db.models]" ||--o{ "DocumentSet [onyx.db.models]" : "queries"
    "Persona [onyx.db.models]" ||--o{ "HierarchyNode [onyx.db.models]" : "scoped_to"
    "Persona [onyx.db.models]" ||--o{ "UserFile [onyx.db.models]" : "references"

    "Persona [onyx.db.models]" {
        int id
        string name
        string system_prompt
        int default_model_configuration_id
        boolean datetime_aware
        int display_priority
    }

详细信息请参阅助手配置。

来源：backend/onyx/db/persona.py:30-45、backend/onyx/server/features/persona/models.py:105-138、backend/onyx/db/persona.py:74-156

---

提示词工程

Onyx 通过将助手的自定义提示词与系统级默认值及上下文信息进行分层组合，构建最终的大语言模型（LLM）输入。PromptSnapshot 类封装了助手的提示词相关字段 backend/onyx/server/features/persona/models.py:71-94。

提示词组件

• 系统提示词：在 PersonaUpsertRequest 中定义，提供"个性"和基本约束 backend/onyx/server/features/persona/models.py:134。
• 任务提示词：关于如何处理用户查询的具体指令 backend/onyx/server/features/persona/models.py:136。
• 日期时间感知：如果启用了 datetime_aware，系统会注入当前日期/时间，帮助模型处理与时间相关的查询 backend/onyx/server/features/persona/models.py:137。

详细信息请参阅提示词工程。

来源：backend/onyx/server/features/persona/models.py:71-94、backend/onyx/server/features/persona/models.py:134-137

---

工具集成

助手可以通过内置工具或通过 OpenAPI 或 MCP（模型上下文协议）的自定义集成获得能力。

工具编排

助手从 Tool 表中定义的可用工具中进行选择 backend/onyx/db/models.py:35。前端识别核心工具，如 SEARCH_TOOL_ID、WEB_SEARCH_TOOL_ID 和 PYTHON_TOOL_ID web/src/refresh-pages/AgentEditorPage.tsx:33-39。

自定义工具和 MCP 工具

• 自定义工具：使用 OpenAPI 定义构建，并通过 /admin/tool/custom 端点进行管理 backend/onyx/server/features/tool/api.py:83-104。
• MCP 服务器：助手可以利用外部 MCP 服务器进行动态工具发现。这些服务器通过 MCPServer 接口进行管理 web/src/lib/tools/interfaces.ts:20-37。

工具选择流程

graph TD
    User["用户"] -->|选择| Agent["代理（角色）"]
    Agent -->|配置了| TIDs["tool_ids（PersonaUpsertRequest）"]
    TIDs -->|映射到| Tbl["Tool（onyx.db.models）"]
    Tbl -->|包含| BuiltIn["内置（SearchTool、PythonTool）"]
    Tbl -->|包含| Custom["自定义（OpenAPI 工具）"]
    Tbl -->|包含| MCP["MCP（模型上下文协议）"]

    BuiltIn -->|通过执行| Loop["run_llm_loop（聊天系统）"]
    Custom -->|通过执行| Loop
    MCP -->|通过执行| Loop

详细信息请参阅工具集成。

来源：web/src/refresh-pages/AgentEditorPage.tsx:33-39、backend/onyx/server/features/tool/api.py:83-104、web/src/lib/tools/interfaces.ts:76-110

---

知识来源

助手可以限定在特定的知识领域内，以确保相关性和安全性。

知识范围限定

1. 文档集：来自连接器的已索引文档集合 backend/onyx/server/features/persona/models.py:108。
2. 层级节点：附加的特定文件夹、空间或频道，用于限定范围搜索 backend/onyx/server/features/persona/models.py:129。
3. 单个文档：固定到助手的特定文档 ID backend/onyx/server/features/persona/models.py:131。
4. 用户文件：用户直接上传的文件，通过 FileReaderTool 路径进行处理 backend/onyx/server/features/persona/api.py:68-81。

向量数据库依赖

依赖语义搜索的知识类型（文档集、层级节点、附加文档）需要向量数据库。如果启用了 DISABLE_VECTOR_DB，这些来源将受到限制，但 user_files 仍然可以访问，因为它们是通过工具中介路径处理的 backend/onyx/server/features/persona/api.py:84-117。

详细信息请参阅知识来源。

来源：backend/onyx/server/features/persona/api.py:68-117、backend/onyx/server/features/persona/models.py:127-131