agentic_huge_data_base / wiki
页面 Onyx · 5.2 提示词工程·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 5.2

5.2 · 提示词工程

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

项目Onyx 章节5.2 状态全文译文 模块智能体运行时、测试、发布与运维、检索、召回与索引、文档对象与元数据
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节提示词工程 上一章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
模块标签
  • 智能体运行时
  • 测试、发布与运维
  • 检索、召回与索引
  • 文档对象与元数据
  • 工作流与编排

章节正文

提示词工程

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

提示工程

相关源文件

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

  • 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
  • backend/onyx/deep_research/dr_loop.py
  • backend/onyx/prompts/chat_prompts.py
  • backend/onyx/prompts/deep_research/__init__.py
  • backend/onyx/prompts/deep_research/dr_tool_prompts.py
  • backend/onyx/prompts/deep_research/orchestration_layer.py
  • backend/onyx/prompts/deep_research/research_agent.py
  • backend/onyx/prompts/prompt_utils.py
  • backend/onyx/prompts/tool_prompts.py
  • backend/onyx/server/query_and_chat/chat_backend.py
  • backend/onyx/server/query_and_chat/models.py
  • backend/onyx/tools/fake_tools/research_agent.py
  • backend/onyx/tools/models.py
  • backend/onyx/tools/tool_implementations/search/search_tool.py
  • backend/onyx/tools/tool_runner.py
  • backend/tests/unit/onyx/chat/test_llm_loop.py
  • backend/tests/unit/onyx/chat/test_llm_step.py

目的与范围

本文档记录了 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 系统提示逻辑

Onyx · Persona 系统提示行为 · 图 1
Onyx · Persona 系统提示行为 · 图 1

当 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。

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

Onyx · 自定义智能体提示定位 · 图 2
Onyx · 自定义智能体提示定位 · 图 2

来源：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）输入消息序列

Onyx · 消息排序规范 · 图 3
Onyx · 消息排序规范 · 图 3

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

标题：深度研究逻辑流程

Onyx · 深度研究提示架构 · 图 4
Onyx · 深度研究提示架构 · 图 4
  • 编排器：管理高级计划执行，限制为 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。

标题：提示缓存前缀识别

Onyx · 提示缓存支持 · 图 5
Onyx · 提示缓存支持 · 图 5

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