agentic_huge_data_base / wiki
页面 Onyx · 5 AI 助手与角色画像·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 5

5 · AI 助手与角色画像（AI Assistants and Personas）

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

项目Onyx 章节5 状态全文译文 模块界面与交互、测试、发布与运维、接口与服务契约、图谱与关系
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节AI Assistants and Personas 上一章4.5 下一章5.1
源码线索
  • 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
模块标签
  • 界面与交互
  • 测试、发布与运维
  • 接口与服务契约
  • 图谱与关系
  • 文档对象与元数据

章节正文

AI 助手与角色画像

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

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
助手实体关系
Onyx · 助手实体关系 · 图 1
Onyx · 助手实体关系 · 图 1

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

来源：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。
工具选择流程
Onyx · 工具选择流程 · 图 2
Onyx · 工具选择流程 · 图 2

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

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