5.2 · Prompt Engineering

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

项目Onyx 章节5.2 状态全文译文模块智能体运行时、测试、发布与运维、检索、召回与索引、文档对象与元数据

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Prompt Engineering 上一章5.1 下一章5.3

源码线索

backend/onyx/chat/chat_state.py
backend/onyx/chat/chat_utils.py
backend/onyx/chat/llm_loop.py
backend/onyx/chat/llm_step.py
backend/onyx/chat/models.py
backend/onyx/chat/process_message.py
backend/onyx/chat/prompt_utils.py
backend/onyx/context/search/models.py
backend/onyx/context/search/pipeline.py
backend/onyx/db/chat.py

模块标签

智能体运行时
测试、发布与运维
检索、召回与索引
文档对象与元数据
工作流与编排

中文译文

Prompt Engineering（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/5.2-prompt-engineering

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

翻译模型：deepseek-chat

原文字符数：11435

项目：Onyx (onyx)

---

提示工程

目的与范围

本文档记录了 Onyx 系统中提示的构建及其集成到大语言模型（LLM）输入中的过程。它详细说明了系统提示的组成、自定义智能体提示、消息历史排序、上下文文件集成以及 Token 预算管理。有关控制提示行为的 Persona 字段配置，请参见助手配置。有关工具如何构建并呈现给大语言模型（LLM）的详细信息，请参见工具集成。

系统提示架构

基础系统提示

系统维护一个默认的基础系统提示，作为所有大语言模型（LLM）交互的基础。该提示通过 get_default_base_system_prompt() 获取 backend/onyx/chat/prompt_utils.py:25-25。

动态组件

基础系统提示会通过 DEFAULT_SYSTEM_PROMPT 中定义的多个上下文相关元素进行动态增强 backend/onyx/prompts/chat_prompts.py:13-28：

组件	替换模式	用途
当前日期时间	`{{CURRENT_DATETIME}}`	通过 `get_current_llm_day_time()` 提供时间上下文 `backend/onyx/prompts/prompt_utils.py:51-51`
引用说明	`{{CITATION_GUIDANCE}}`	提醒大语言模型（LLM）使用 `[1]`、`[2]` 格式引用来源 `backend/onyx/prompts/chat_prompts.py:40-44`
提醒标签	`{{REMINDER_TAG_DESCRIPTION}}`	注入格式或行为约束 `backend/onyx/prompts/chat_prompts.py:7-7`

最终组装在 build_system_prompt() 中完成，该函数根据 Persona 的配置合并这些字符串 backend/onyx/chat/prompt_utils.py:24-24。

来源：backend/onyx/chat/prompt_utils.py:24-25、backend/onyx/prompts/chat_prompts.py:13-44、backend/onyx/prompts/prompt_utils.py:51-51

Persona 系统提示行为

每个 Persona backend/onyx/db/models.py:77-77 都有一个 system_prompt 字段。replace_base_system_prompt 布尔值决定了拼接逻辑。

标题：Persona 系统提示逻辑

graph TD
    PersonaPrompt["Persona.system_prompt"]
    ReplaceFlag["Persona.replace_base_system_prompt"]
    BasePrompt["基础系统提示<br/>(get_default_base_system_prompt)"]

    ReplaceFlag -->|true| CustomOnly["仅使用自定义提示<br/>作为系统消息"]
    ReplaceFlag -->|false| Prepend["将自定义提示前置到基础提示前<br/>作为系统消息"]

    PersonaPrompt --> ReplaceFlag
    BasePrompt --> Prepend
    PersonaPrompt --> CustomOnly
    BasePrompt -.未使用.-> CustomOnly

当 replace_base_system_prompt 为 False（默认值）时，自定义提示会被前置到基础提示之前 backend/onyx/server/query_and_chat/chat_backend.py:140-143。

来源：backend/onyx/server/query_and_chat/chat_backend.py:136-143、backend/onyx/chat/prompt_utils.py:24-25

自定义智能体提示定位

custom_agent_prompt 通过 get_custom_agent_prompt() 解析 backend/onyx/chat/chat_utils.py:30-30。如果聊天会话关联了一个项目，则项目的智能体模板优先于 Persona 的系统提示 backend/onyx/chat/chat_utils.py:138-142。

标题：自定义智能体提示解析

graph TD
    GetPrompt["get_custom_agent_prompt(persona, chat_session)"]
    HasProject{聊天会话有<br/>project_id?}
    UseProject["使用 project.agent_template"]
    UsePersona["使用 persona.system_prompt<br/>(如果 replace_base=true)"]
    NoCustom["无自定义智能体提示"]

    GetPrompt --> HasProject
    HasProject -->|是| UseProject
    HasProject -->|否| CheckReplace{persona.replace_base<br/>_system_prompt?}
    CheckReplace -->|true| UsePersona
    CheckReplace -->|false| NoCustom

来源：backend/onyx/chat/chat_utils.py:138-159、backend/onyx/chat/process_message.py:30-30

消息历史构建

construct_message_history() 函数是组装最终大语言模型（LLM）输入数组的核心逻辑 backend/onyx/chat/llm_loop.py:14-14。

消息排序规范

该函数按以下严格顺序生成消息：

标题：大语言模型（LLM）输入消息序列

graph LR
    System["1. 系统提示"] --> History["2. 截断后的历史<br/>(最后一条用户消息之前)"]
    History --> CustomAgent["3. 自定义智能体提示"]
    CustomAgent --> ContextFiles["4. 上下文文件"]
    ContextFiles --> ForgottenFiles["5. 已遗忘文件元数据"]
    ForgottenFiles --> LastUser["6. 最后一条用户消息"]
    LastUser --> AfterUser["7. 工具调用与响应"]
    AfterUser --> Reminder["8. 提醒消息"]

来源：backend/onyx/chat/llm_loop.py:14-14、backend/onyx/chat/process_message.py:30-32

Token 预算管理

Token 分配通过计算必需组件（系统提示、工具、最后一条用户消息）的预留 Token，然后将剩余部分用于聊天历史来实现 backend/onyx/chat/prompt_utils.py:53-53。

组件	计算逻辑
系统提示	`token_counter(prompt_string)`
工具	每个工具预留 `256` 个 Token `backend/onyx/server/query_and_chat/chat_backend.py:122-122`
用户输入	为长输入预留 `2000` 个 Token `backend/onyx/server/query_and_chat/chat_backend.py:124-124`
历史	剩余预算；从最旧的消息开始截断 `backend/onyx/chat/compression.py:34-34`

来源：backend/onyx/chat/prompt_utils.py:53-53、backend/onyx/server/query_and_chat/chat_backend.py:118-131、backend/onyx/chat/compression.py:34-34

上下文文件集成

文档表示

上下文文件和搜索结果通过 build_file_context 工具集成到提示中 backend/onyx/chat/chat_utils.py:67-67。

仅元数据：如果文件类型仅需要元数据（例如大文件），提示会包含文件名和 ID，并指示大语言模型（LLM）使用 file_reader 工具 backend/onyx/chat/chat_utils.py:80-85。
全文：对于较小的基于文本的文件，完整内容会被包裹在 "File: {filename}" 和 "End of File" 标记之间 backend/onyx/chat/chat_utils.py:93-93。

已遗忘文件机制

当历史被截断时，会跟踪附加到已丢弃消息中的文件。系统会创建一条元数据消息，列出这些"已遗忘"的文件，以便大语言模型（LLM）在需要调用工具时仍能感知它们的存在 backend/onyx/chat/models.py:48-49。

来源：backend/onyx/chat/chat_utils.py:67-111、backend/onyx/chat/models.py:44-49

深度研究提示架构

深度研究使用一个递归编排循环，并配有专门的系统提示 backend/onyx/deep_research/dr_loop.py:83-83。

标题：深度研究逻辑流程

graph TD
    Start["用户查询"]

    Start --> Clarification["1. 澄清阶段<br/>CLARIFICATION_PROMPT"]
    Clarification -->|需要信息| AskUser["提出澄清性问题"]
    Clarification -->|信息充足| Plan["2. 研究规划<br/>RESEARCH_PLAN_PROMPT"]

    Plan --> Orchestrator["3. 编排循环<br/>ORCHESTRATOR_PROMPT"]

    Orchestrator --> ResearchAgent["调用 research_agent 工具<br/>RESEARCH_AGENT_PROMPT"]
    ResearchAgent --> SubLoop["子循环：search 与 open_url"]
    SubLoop --> IntermediateReport["RESEARCH_REPORT_PROMPT"]

    IntermediateReport --> Orchestrator
    Orchestrator --> FinalReport["4. 最终报告生成<br/>FINAL_REPORT_PROMPT"]

编排器：管理高级计划执行，限制为 MAX_ORCHESTRATOR_CYCLES（8 个周期）backend/onyx/deep_research/dr_loop.py:94-94。
研究智能体：执行实际的搜索和 URL 打开任务 backend/onyx/tools/fake_tools/research_agent.py:42-45。
最终报告：使用 FINAL_REPORT_PROMPT 综合所有收集到的信息 backend/onyx/prompts/deep_research/orchestration_layer.py:37-37。

来源：backend/onyx/deep_research/dr_loop.py:83-113、backend/onyx/tools/fake_tools/research_agent.py:42-47、backend/onyx/prompts/deep_research/orchestration_layer.py:36-50

提示缓存支持

系统通过 process_with_prompt_cache() 实现提示缓存 backend/onyx/llm/prompt_cache/processor.py:42-42。它根据 PROMPT_CACHE_CHAT_HISTORY 配置识别消息历史中可缓存的部分 backend/onyx/chat/llm_step.py:20-20。

标题：提示缓存前缀识别

graph TD
    Start["遍历历史"]
    CheckType{消息类型<br/>可缓存?}
    CheckFlag{msg.should_cache<br/>== True?}
    AllPrevCache{所有之前的消息<br/>都可缓存?}

    Start --> CheckType
    CheckType -->|SYSTEM, USER,<br/>ASSISTANT,<br/>TOOL_RESPONSE| CheckFlag
    CheckType -->|其他| Start

    CheckFlag -->|是| AllPrevCache
    CheckFlag -->|否| MarkNonCache["标记为不可缓存"]

    AllPrevCache -->|是| UpdateIdx["更新缓存索引"]
    AllPrevCache -->|否| MarkNonCache

    UpdateIdx --> Start

来源：backend/onyx/llm/prompt_cache/processor.py:42-42、backend/onyx/chat/llm_step.py:20-20