上下文工程最佳实践

有效的上下文基础可确保智能体在合适的时间访问相关知识，以完成当前任务。正确实施后，它能提高准确性，提升性能并降低令牌成本。

本节概述了如何使用上下文基础配置和维护上下文来源，包括索引设置、架构设计和持续评估的最佳实践。

有关上下文基础服务的详细信息，请参阅专属文档：《关于上下文基础》。

了解什么是上下文基础

智能体通过上下文基础连接到企业知识，例如文档、常见问题解答、电子邮件和标准操作程序 (SOP) 等。您在 Orchestrator 中创建索引，并将其附加到 Studio Web 中的智能体，以启用此连接。

上下文基础可帮助智能体：

• 对业务专属数据进行推理。
• 避免幻觉或捏造。
• 使用最新的受监管知识作出响应。
• 在配置了架构约束的情况下引用来源。

设置上下文基础的最佳实践

为了构建可靠、响应迅速的智能体，请在设计和调整上下文时遵循以下核心实践：

使用有版本信息的描述性索引名称

使用明确、一致的模式为索引命名。示例：HR-Policies-2025-Q3。

这样可以轻松地：

• 回滚到之前的索引版本。
• 使用不同的知识库执行 A/B 测试。
• 持续跟踪更新。

当内容发生重大变化时，在 Orchestrator 中创建新索引，并对智能体定义进行相应更新。

选择正确的提取模式。

创建索引时，请选择适合您内容的提取模式：

• 基本模式：适合大多数内容为纯文本的文档。
• 高级模式：用于文本和图片相结合的文件（例如，经过扫描的 PDF 或信息图表）。

这会影响覆盖范围和 OCR 相关成本。根据文档类型以及可视化内容对检索的重要程度进行选择。

保持规律的同步节奏

随时更新索引可确保智能体引用最新信息。使用 Orchestrator 中的“同步”操作或 Studio 中的“更新上下文基础索引”活动刷新索引内容。您可以依据源内容的更新频率制定定期同步计划。

校准结果数量和阈值分数

• 结果数量：调整此设置可控制检索的上下文数据块数量。结果越多，检索率就越高，但也会增加令牌的使用量。
• 阈值：过滤相关性低的上下文。默认值为 0。如果返回的不相关段落过多，您可以提高阈值以提高精度。但是，请注意，将阈值设置为高于 0（零）的值意味着可能从响应中过滤掉相关数据块，这可能会导致幻觉。

请平衡这些参数，以确保情高信号上下文，同时不超过令牌上限。

在智能体设计中使用明确的上下文描述

将上下文索引添加到智能体时，请提供索引所涵盖内容的简短准确描述。这有助于指导智能体在执行期间检索和使用知识。

使用多个上下文源时，描述特别有用。

将架构与智能体预期保持一致

在适用的情况下定义响应架构，JSON 等结构化输出尤其如此。这确保了智能体提供正确的响应格式，并且仅包含上下文中的信息。

在系统提示中包含架构示例，以提高可靠性。

迭代时间和方式

在以下情况下，重新访问上下文配置：

• 智能体缺少预期结果。
• 追踪记录中出现不相关的内容。
• 智能体超过令牌上限或因“超出令牌上限”错误而失败。
• 文档架构发生变化。
• 出现新的用例或作用域扩展。

使用测试和生产运行中的追踪日志，诊断问题是否与上下文质量、数量或索引参数有关。

常见错误及其修复方法

使用此表格识别和解决常见的上下文基础问题。每行都突出显示了追踪记录中可能出现的检测信号以及建议纠正措施。

表 1. 上下文基础问题排除

错误	检测信号	建议修复措施
尽管索引中应该包含相关文档，但智能体未按预期做出响应	未找到结果	确认最新数据，添加相关文档并同步索引 降低阈值
缺少预期答案	追踪记录显示高阈值过滤	降低阈值或提高文档覆盖率
上下文窗口溢出	智能体出现“超出令牌上限”故障	减少结果数量或缩短用户输入
返回的信息已过时	追踪记录显示过时的时间戳	同步或重建索引；重新发布智能体

评估上下文质量

使用 Agent Builder 中的评估运行，测试您的上下文来源对智能体目标的支持情况。

评估运行应：

• 包括真实世界的各种提示。
• 查看追踪记录，以检查检索了哪些数据块。
• 更新或替换索引时包括回归测试。

您还可以使用带有模拟上下文的工具模拟运行，以在进行完整索引更新之前预览性能。

摘要清单

使用以下清单，确保您的上下文基础设置遵循最佳实践：

• 索引名称有版本信息且为描述性。
• 提取模式与文档类型匹配。
• 定期同步索引。
• 结果数量和阈值已调整。
• 上下文描述具有信息性。
• 在提示中定义并实施架构。
• 使用追踪日志跟踪常见错误并加以解决。

示例提示模板

使用以下模板作为智能体系统提示的起点。对其进行自定义，以适合您的特定用例。

问答/知识查询

You are an enterprise knowledge assistant.
Goal: Answer user questions using ONLY approved company documents.
Constraints:
- Cite each answer with source title and section.
- If confidence is low or no relevant context was retrieved, ask a clarifying question instead of guessing.
- Respond in Markdown unless JSON is requested.

# Processing Steps
1. Interpret the user question.
2. Review retrieved context below.
3. Use only information found in context; do not fabricate.
4. Provide a concise answer and cite sources.

结构化提取和验证

You are an extraction agent that maps document content into a structured schema.
Goal: Populate all required fields from retrieved document snippets.
Constraints:
- Return valid JSON matching the schema.
- Use null if field not found; do NOT guess.
- Provide a confidence score 0‑1 for each field.
- Include source_span metadata (doc_id, chunk_id).

# Steps
1. Read user instruction for target doc type.
2. Review retrieved context.
3. Extract fields.
4. Validate required fields; request escalation if missing critical values.

推理和操作选择

You are an operations triage agent.
Goal: Decide the next best action based on policies and current case details.
Constraints:
- Choose only from the allowed actions list.
- Provide short rationale.
- Output as JSON: {"action":string,"reason":string,"evidence_sources":[...]}

# Allowed Actions
{{ACTION_LIST}}