智能体部署（Agentic Deploy）证据
本文档描述智能体部署如何处理结构化与非结构化证据、当前的实现方式，以及后续计划。
数据与权威性
结构化数据
结构化数据由 BenchmarkRecord 组成：模型、硬件、运行时、工作负载、候选配置、实测性能指标、结果以及失败原因。记录存放在 agentic_benchmark_records 中，对于性能数字、失败事实和候选级别的预测具有权威性。
实时集群概览同样是结构化证据，且具有最高权威性：它决定候选方案是否满足当前的显存、GPU、CPU 缓冲区等硬约束。历史基准测试、AIC 和 AI 都不能覆盖实时资源的结论。
非结构化数据
非结构化数据包括部署日志、性能剖析（profiling）轨迹、制品摘要、Guide、GitHub 内容、论文、规划快照摘要，以及来自云存储的、计划纳入的原始基准测试报告。可搜索的投影（projection）存放在 OpenSearch 中；原始制品保留在受控的文件系统中，云端报告则保留在其授权的存储位置。
云端基准测试报告的集成尚未实现。计划是先对受 ACL 控制的摘要和对象版本建立索引以便发现，然后在租户/ACL 控制下获取固定的源版本，并在使用前验证其内容哈希。需要提取模型、硬件、运行时、工作负载、拓扑、实测指标、结果和溯源信息；校验单位与必填字段；归一化为请求级别的局部 BenchmarkRecord 对象。字段缺失、来源不可验证，或只有估算值的报告无法成为实测记录。未提取或未校验的报告文本仅用于诊断，不能影响数值预测、失败阻断或确定性排序。合格的记录仍需经过结构化的基准测试兼容性过滤和相似度计算；仅凭检索到并不能确立性能结论。
日志、轨迹、制品和快照摘要仅用于诊断与解释。经过 ACL 过滤、版本固定的 Guide、GitHub 和论文摘要，也可以为方法适用性、兼容性约束和偏好权衡提供 AI 推荐功能。非结构化数据对 TTFT、TPOT、吞吐量、置信度或 SLO 不具有权威性；它不能直接生成或阻断候选方案，也不能改变确定性排序。
构建证据
结构化基准测试证据
服务端首先针对加速器、后端、量化方式、拓扑、单 GPU 显存以及安全的时间窗口应用粗粒度的数据库过滤。成功和失败的记录都会被保留。随后 BenchmarkEvidenceRetriever 计算模型、硬件、由用例推导出的工作负载、候选配置以及 SLO 性能相似度，并叠加时间/运行时衰减，从而生成两个独立的视图：
| 视图 | 内容 | 消费方 |
|---|---|---|
| 原始样本 | 每个候选方案最多五条相关的 BenchmarkRecord 对象，包括实测指标、结果、失败原因以及 match_similarity | AI 评分 |
| 聚合输入 | PerformanceScoreInput，包含预测指标、状态、置信度、有效样本量、失败阻断情况以及引用 | 确定性规划器（Deterministic Planner） |
match_similarity 仅表示某条历史记录与当前目标的相关程度。它不是部署成功概率，也不是对当前性能的保证。聚合的 confidence 和有效样本量只属于确定性路径。
当前请求不需要直接的工作负载输入。带版本号的 resolve_workload_signals() 会将用例映射为查询画像 $q$，包括 token 长度、并发量、请求速率、共享前缀和预填充（prefill）信号。显式的工作负载覆盖只会覆盖对应字段，并会记录其来源。如果映射未知，或者无法提供可比对的字段，则不会捏造工作负载；相关历史记录也就无法成为高相似度的性能证据。
对于通过数据库硬过滤的历史记录 $r$ 和当前候选查询 $q$，检索器会计算配置/工作负载以及性能目标的相似度 $S$：
$$ S = 0.20S_{model} + 0.15S_{hardware} + 0.15S_{workload} + 0.15S_{configuration} + 0.35S_{SLO} $$
这些权重反映的是实测历史性能对决策的价值，而不是为了拟合有限的历史样本。$S_{SLO}$ 具有最大的单项权重 $0.35$，更偏向于那些 TTFT、TPOT 和工作负载承载能力都符合当前目标的记录；下文的"最弱分量"约束可以防止配置相同但性能不合适的记录获得过高分数。模型、硬件和工作负载分别保留 $0.20$、$0.15$ 和 $0.15$ 的权重，以确保性能是在可比的环境和请求形态下被解读的。配置的权重为 $0.15$，使得 TP、副本数和优化手段能够影响排序。硬过滤已经确保了加速器、后端、量化方式、拓扑和单 GPU 显存以及时间窗口的兼容性，这里不再重复计入。
这些系数、子分量系数、时间/运行时半衰期、最小 match_similarity，以及失败阻断阈值目前是固定的，并与模式版本（schema version）一起记录在规划快照中。未来应该可以按租户或部署策略选择一个带版本号的 EvidenceSimilarityPolicy。只允许使用经过离线回放验证、服务端加入许可清单的预设；并记录策略 ID 和所有参数。禁止任意按提示词或按 UI 调整权重。新策略在成为默认策略之前，必须在历史回放中与默认策略对比排序稳定性、SLO 命中率和漏判的负面证据。
如果量化方式或模型架构不同，则 $S_{model}=0$；否则：
$$ S_{model} = 0.45S_{family} + 0.25 + 0.20e^{-0.8|\ln(p_r/p_q)|} + 0.10S_{tokenizer} $$
对于同一模型家族，$S_{family}$ 为 $1$，否则为 $0.15$；对于相同的分词器（tokenizer），$S_{tokenizer}$ 为 $1$，否则为 $0.5$。对于 MoE，$p$ 优先取激活参数量。硬件相似度仅比较 GPU 数量：
$$ S_{hardware} = 0.7 + 0.3e^{-|\ln(g_r/g_q)|} $$
$S_{workload}$ 对平均输入长度、P95 输入长度、平均输出长度、并发量和请求速率这五个对数比值评分取平均，再加上共享前缀比例和预填充比例这两个 $1-|x_r-x_q|$ 评分。$q$ 中的取值来自上文所述的用例映射或显式覆盖。候选配置相似度为：
$$ S_{configuration} = 0.4e^{-|\ln(TP_r/TP_q)|} + 0.4e^{-|\ln(R_r/R_q)|} + 0.2J_{optimization} $$
$J_{optimization}$ 是两个优化手段集合的 Jaccard 重叠度；数据库硬过滤已经确保了拓扑完全相同。
用户显式指定的 SLO 优先级最高。当对应目标缺失时，UseCasePerformanceEstimate 中的 TTFT、TPOT 和工作负载上限会作为考虑不确定性的软目标。对于每一个必需的延迟上限 $L$ 和历史实测延迟 $m_r$，计算：
$$ s_{latency} = e^{-2\max(0, \ln(m_r/L))} $$
当达到目标时该项为 $1$，达到目标延迟两倍时为 $0.25$，并随偏差增大迅速趋近于 $0$。对所需工作负载承载能力 $c_q$ 和历史上能支持的承载能力 $c_r$ 施加相同的单边惩罚：
$$ s_{capacity} = e^{-2\max(0, \ln(c_q/c_r))} $$
$$ S_{SLO} = \min(s_{TTFT}, s_{TPOT}, s_{capacity}) $$
只对请求中实际存在的目标取最小值。如果历史记录缺少某项显式 SLO 所需的指标，该记录就不能成为高相似度的性能证据，尽管它仍可以保留作为诊断用途。如果估算的目标过于不确定，或指标不可用，则不会捏造 $S_{SLO}$：此时会降级证据状态，以确保一个没有性能目标支撑的高分记录无法取代那些满足显式 SLO 的记录。
$S$ 是基础相似度：它描述的是某条基准测试记录的模型、硬件、工作负载、配置和实测性能与当前目标的契合程度。
当前实现还会计算时间衰减和运行时衰减：
$$ W = S \times D_{time} \times D_{runtime} $$
本文档中将 $W$ 称为匹配相似度（match similarity）。它在基础相似度 $S$（已包含 SLO 性能契合度）的基础上叠加了时间/运行时效应，表达的是该历史记录与当前决策的相关程度。AI 评分读取按 $W$ 排序后的原始样本。确定性回退路径使用 $W$ 来计算加权指标平均值、有效样本量、确定性的 confidence、失败阻断以及 SLO/性能排序。AI 不会接收这些聚合值。当前负载字段仍然命名为 match_confidence，但其携带的是本文档中定义为 match_similarity 的 $W$。
非结构化诊断证据
日志、轨迹、制品和外部材料会被转化为有界的 DiagnosticEvidenceProjection 对象，具有固定的 evidence_id、内容哈希、源版本、租户、ACL 以及必要的运行时元数据。使用前，制品必须通过针对其 manifest 和文件 SHA-256 的来源校验。
OpenSearch 查询必须首先应用租户/ACL 过滤。默认使用 BM25，只有当调用方显式提供了向量时才使用 kNN。投影是可重建的。当 OpenSearch 不可用、索引过期或没有结果时，特征/诊断为空，且不会影响确定性规划。
云端基准测试报告的两阶段检索
未来的受控导入器会定期或按事件从已配置的云端位置读取历史报告，仅为了发现而创建 OpenSearch RAG 投影。它必须校验来源身份、租户/ACL、报告模式版本、内容哈希、采集时间以及制品 manifest。使用稳定的源报告 ID 和哈希进行幂等去重。无法验证的报告不会生成投影；无法完整归一化的报告仅用于解释，不能作为性能规划输入。
第一阶段通过租户/ACL 过滤检索报告投影，以定位可能相关的原始报告。BM25/kNN 命中只表示文本相关性，而不是基准测试的可比性、match_similarity 或性能结论。外部报告不会被写入 agentic_benchmark_records；投影只保留云端 URI、生产者/模式版本、哈希、源报告 ID，以及获取原始报告所需的受控元数据。
第二阶段只处理被检索到的报告。服务端会重新校验来源 manifest/哈希、ACL 和模式，然后在本次规划请求范围内，将完全可解析的报告临时归一化为与在线采集相同形态的 BenchmarkRecord：模型、加速器/运行时、工作负载、候选配置、TTFT/TPOT/吞吐量、结果以及失败原因。临时记录不会被持久化。缺少性能比对字段的报告只能用于诊断/解释，不能用于给候选方案打分。
通过第二阶段的临时记录与本地持久化的记录会经历相同的硬过滤和 $S \rightarrow W$ 计算，得到含义相同的 match_similarity。对于每个通过硬过滤的候选方案，原始样本视图会为 AI 评分提供按 $W$ 降序统一排序的、最多五条基准测试证据样本，每条样本都包含 match_similarity、指标、结果、失败原因以及可追溯的来源引用。不存在单独的来源配额。
两条消费路径
确定性路径
只有当 AI 未配置、生成/评分失败，或响应无效时，确定性路径才会成为最终的决策路径。对于每个通过硬过滤的候选方案，它会在所有匹配样本上计算 $D_{time}$、$D_{runtime}$ 和 $W$，然后构建 PerformanceScoreInput。
聚合后的历史记录只有两种作用：
- 如果存在数量足够多、且足够相似的失败记录，则设置
has_blocking_negative_evidence并排除该候选方案，以避免再次推荐一个已知会失败的配置。 - 如果成功的历史记录数量足够多、且足够相似，能够支撑稳定的性能结论，则首先比较所请求 SLO 的达标情况；若打平，则依次比较确定性
confidence、有效样本量、TTFT、TPOT、吞吐量和错误率。
样本过少或相似度不足、指标缺失，或存在未解决的失败证据时，都不意味着性能上的优势或劣势。此时改为使用精确的 AIC 匹配结果和现有启发式方法为该候选方案排序。
该路径不消费非结构化的 OpenSearch 内容，也不允许 AI 改写失败阻断、SLO 结论或排序。
AI 路径
AI 的生成和评分是两个独立的阶段。生成器首先检索与模型、可用资源和所请求 SLO 匹配的历史基准测试记录。只有经过验证的候选配置及其受控的溯源信息，才可以作为候选先验（candidate priors）进入生成器的 prompt。如果没有符合条件的历史记录，则省略先验，仅从常规输入生成提案。每个提案都必须通过 CandidateValidator。
对于每个可行的 provider，AI 生成器必须首先提出最小资源拓扑方案：满足内存约束的最低 TP，以及每个服务角色一个副本。显式的 provider 偏好只能用于选择方法，不能自行提高 TP 或副本数。额外的资源需要显式的 SLO 或完整的 AIC 预测来支撑。从一个放宽搜索得到的锚点进行扩展，仍然只是一个需要验证的估算值。
AI 评分首先会筛选出最多十个通过硬过滤的候选方案：按确定性顺序为每个 provider 保留最佳候选方案，然后按排名补足剩余名额。只有入选的候选方案才会进入 AI，每个候选方案最多附带五条按相似度排序的真实历史基准测试记录。原始基准测试记录描述的是实测的历史行为：AI 可以比较 TTFT、TPOT、吞吐量、结果和失败原因，例如避免选择之前在类似工作负载下导致 OOM 的候选方案。经过 ACL 过滤、有界、版本固定的 Guide/GitHub/论文特征包尚未集成到 AI 评分中。未来的特征包只能用于提示方法前提条件、版本兼容性和操作者偏好；它们不是实测数据，不能用来确立 TTFT、TPOT、吞吐量、SLO 或置信度。
AI 不能生成新的候选方案，也不能将非结构化特征解读为性能实测数据。响应只能从服务端提供的候选方案 ID 中选择。无效、超时或不可用的响应会回退到确定性路径。
生成器 Prompt 的构建与示例
生成是一个工具调用（tool-calling）阶段，而不是一个可以直接部署的配置目录。服务端构建的第一条用户消息只包含 cluster_id、model、operator_preference 和 deployment_intent，并剥离了实时资源/AIC/证据相关字段。系统 prompt 固定了 provider 的许可清单/语义、最小资源拓扑原则、PD 字段契约，以及只读 MCP 许可清单。它禁止臆造 provider、硬件、AIC 结果或基准测试事实，也禁止写入、部署、审批、删除和端口转发操作。
第一轮只暴露 get_cluster_overview 和 search_candidates，且要求并行调用；sourceIds 必须包含 aic。服务端使用 cluster_id 和 sourceIds 对参数进行归一化，并返回有界的结果。后续调用仍然被限制在许可清单内的只读工具范围内。模型只能通过 submit_candidate_proposals 提交一到十个提案；CandidateValidator 会独立地重新计算内存、GPU、CPU 缓冲区、PD 完整性和去重情况。当前实现不会注入任何历史基准测试先验。未来的先验必须是一个单独的有界字段，只包含经过验证的候选方案/溯源信息，不包含聚合指标、置信度、$N_{eff}$、SLO 结论或未经授权的数据。