# Azure QnA Maker 运行时 QueryDTO 接口详解

## 引言

在人工智能与自然语言处理技术快速发展的今天，知识库问答系统已成为企业实现智能化客户服务、内部知识管理的重要工具。Microsoft Azure 提供的 QnA Maker 服务正是这一领域的领先解决方案。在使用该服务时，开发者需要通过 `@azure/cognitiveservices-qnamaker-runtime` 包与知识库进行交互。其中，**QueryDTO 接口**作为 POST 请求体的核心结构，承担着将用户查询请求标准化、参数化的重要职责。本文将对该接口进行全面深入的技术剖析，帮助开发者准确理解其结构、属性及实际应用方式。

## 一、QueryDTO 接口概述

QueryDTO（Query Data Transfer Object）是 Azure QnA Maker 运行时中用于查询知识库的标准请求体结构。该接口定义了一个完整的数据传输契约，使得开发者在向知识库发送查询请求时能够遵循统一规范。其设计体现了灵活性与精确性的结合——既允许用户通过自然语言提问，也支持通过精确的 QnA ID 获取特定答案，同时还提供了多种参数用于控制查询行为和优化搜索结果。

从架构角度来看，QueryDTO 位于客户端应用程序与 QnA Maker 知识库之间的数据交换层。它封装了所有必要的查询参数，并通过序列化过程转换为 JSON 格式，最终通过 HTTP POST 请求发送至服务端点。这一设计使得客户端无需关心服务端的内部处理逻辑，只需按照接口规范构造适当的数据结构即可。

## 二、接口属性全面解析

QueryDTO 接口包含九个主要属性，每个属性都有其独特的功能定位和使用场景。以下将逐一深入分析各个属性的技术细节。

### 1. context（上下文对象）

**类型**：QueryDTOContext（可选）

`context` 属性承载着与先前问答交互相关的会话信息。在多轮对话场景中，这一属性尤为重要。它允许客户端传递前一次 QnA 对话的上下文状态，使得 QnA Maker 能够理解当前问题与前文之间的关联，从而实现连贯的多轮对话体验。

**技术实现**：QueryDTOContext 本身是一个对象，包含 `qnaId` 和 `previousQnaId` 等字段。其中 `qnaId` 表示当前答案对应的 QnA ID，而 `previousQnaId` 则表示上一个问题的 QnA ID。通过维护这一上下文链，系统能够更准确地理解指代性问题和后续追问。

**应用场景**：例如用户先询问“如何重置密码”，系统返回相应答案；接着用户追问“需要多久生效”，系统依靠 context 属性即可判断此问题与前文密码重置话题相关，从而给出精确回答。

### 2. isTest（测试索引标记）

**类型**：boolean（可选）

`isTest` 属性用于指定查询是否针对测试索引执行。在 QnA Maker 开发流程中，通常会将知识库分为测试环境和生产环境。开发阶段，可以通过在 Azure 门户中发布到测试索引来验证知识库的准确性和完整性，而不会影响面向最终用户的生产知识库。

**默认行为**：当此属性未设置或设置为 `false` 时，查询将默认指向已发布的生产索引。只有当显式设置为 `true` 时，查询才作用于测试索引。

**实践建议**：在开发和调试阶段，建议始终将 `isTest` 设置为 `true`，以避免意外消耗生产资源或在生产环境尚未准备好时暴露不成熟的答案。

### 3. qnaId（精确问题标识）

**类型**：string（可选）

`qnaId` 属性提供了一种绕过问题匹配机制的直接查询方式。当设置为特定的 QnA ID 时，QnA Maker 将直接返回该 ID 对应的答案，而不再执行问题文本与知识库问题对之间的相似度匹配。

**优先级规则**：根据官方文档，当 `qnaId` 与 `question` 同时存在时，`qnaId` 拥有更高的执行优先级。这意味着系统会直接使用该 ID 检索答案，完全忽略 `question` 字段。

**适用场景**：
- 在知识库结构调整或更新后，需要验证特定条目的可用性
- 实现FAQ页面中的“点击查看更多”功能，直接加载对应详细解答
- 在多轮对话中，需要通过已知 ID 获取特定知识点进行补充说明

### 4. question（用户问题）

**类型**：string（可选）

`question` 属性是查询知识库的主要载体，用于存放用户以自然语言形式提出的问题。QnA Maker 服务将对该文本进行深度语义理解，通过关键字匹配、词性分析、同义词扩展、上下文关联等自然语言处理技术，在知识库中找出与之最匹配的问答对。

**输入限制**：微软官方建议问题文本长度不超过1000个字符，过长的查询可能影响匹配准确性和响应速度。合理简洁的问题表述通常能获得更佳的匹配结果。

**可选性质**：虽然该属性是常用查询方式，但它为可选字段，因为存在 `qnaId` 等替代查询方式。但若既不提供 `qnaId` 也不提供 `question`，请求将无法有效执行。

### 5. rankerType（排序器类型）

**类型**：string（可选）

`rankerType` 属性允许开发者控制知识库答案的排序算法。默认情况下，QnA Maker 使用混合式排序器，该排序器综合了关键词匹配和相关度排名等多种技术。而设置为 `'QuestionOnly'` 时，系统将仅依据问题文本相似度进行匹配和排序，不参考其他辅助信息。

**各类型的优劣比较**：
- **默认排序器**：性能全面，适合大多数场景，能够处理更复杂的语义理解
- **QuestionOnly 排序器**：匹配逻辑更纯粹，排除了其他干扰因素，适合需要高度精确问题-答案对应关系的场景，但可能忽略了一些潜在相关但措辞不同的匹配结果

**使用建议**：在知识库问题表述清晰、用户查询模式相对固定的情况下，可选择 QuestionOnly 模式提升效率；而在面对多样化提问场景时，建议保留默认排序器以获得更好的泛化能力。

### 6. scoreThreshold（分数阈值）

**类型**：number（可选）

`scoreThreshold` 属性设置了一个置信度分数线，只有同时满足以下条件的答案才会被返回：
- 匹配分数高于等于该阈值
- 在所有高分候选中排名靠前

**取值范围**：该值通常在 0 到 100 之间（具体取决于服务实例的分数体系）。较高的阈值（如 70-80）意味着系统只会返回高置信度的答案，减少错误答案的出现概率；较低的阈值（如 30-40）则会扩大答案范围，适合需要探索性查询或知识库覆盖不足的情况。

**最佳实践**：
- 在初期调试阶段，可设置较低阈值（0-20）以查看所有潜在匹配结果
- 上线生产环境后，根据实际业务需求将阈值调至 50-70 之间
- 当知识库内容质量较高时，可适当提高阈值以减少噪音干扰

### 7. strictFilters（严格过滤条件）

**类型**：MetadataDTO[]（可选）

`strictFilters` 属性是强大的知识库筛选工具。它允许开发者附加一组元数据过滤条件，系统只会返回同时包含这些元数据的问答对，从而实现对查询结果的范围限定。

**MetadataDTO 结构**：该数组中的每个元素包含 `name` 和 `value` 两个字段，分别代表元数据的键名和键值。例如，可以定义 `{ name: "category", value: "technical" }` 来筛选技术类问题。

**多条件逻辑**：当传入多个 MetadataDTO 时，各个过滤条件之间默认采用 "与"（AND）逻辑，即答案需满足所有条件才可返回。这为复杂场景下的精确筛选提供了支持。

**典型应用**：
- 按产品线筛选：只查询某个特定产品的 FAQ
- 按部门筛选：仅提取销售部或技术部的相关问答
- 按标签筛选：获取特定功能模块的帮助内容

### 8. top（最大返回数）

**类型**：number（可选）

`top` 属性限制了每次查询返回的答案最大数量。这一参数对于控制响应体大小、减少网络传输量和提高用户体验都有实际意义。

**合理取值**：默认情况下，若未指定此参数，系统通常返回一个最匹配的答案。当设置为更大的值（如 3-5）时，客户端可以同时获得多个候选答案，用于显示“猜你想要”等功能。

**性能考量**：较大的 `top` 值意味着更多的数据处理和传输量，会增加响应时间。因此建议将其控制在合理范围内，一般情况下 3-5 个候选答案已足够应对多数场景。

### 9. userId（用户标识）

**类型**：string（可选）

`userId` 属性用于标识发起查询的最终用户。该标识符可以被 QnA Maker 服务用于用户行为分析、个性化回答定制和对话上下文维护等目的。

**使用价值**：
- 在后续的 Analytics 中统计不同用户的使用模式和偏好
- 为特定用户群体提供定制化回答内容
- 在多用户参与的场景中区分不同会话

**注意事项**：此字段为可选字段，且不会影响核心查询功能。但出于数据分析的完整性考虑，建议在用户认证后传入具有唯一性的用户标识。

## 三、接口使用实践指南

### 请求构造示例

以下代码展示了如何构造一个包含多个属性的 QueryDTO 对象（下文以伪代码示之）：

```
const queryDTO = {
  question: "如何重置密码",
  top: 3,
  scoreThreshold: 50,
  isTest: false,
  strictFilters: [{"name": "category", "value": "technical"}],
  userId: "user123",
  context: {"previousQnaId": 123, "qnaId": 456}
};
```

### 常见错误及规避方法

1. **缺失核心定位条件**：既不提供 `question` 也不提供 `qnaId`，导致请求无效。解决方案是至少传入一项作为查询入口。
2. **scoreThreshold 过高或过低**：阈值为 100 时可能找不到任何答案；为 0 时可能包含大量无关结果。
3. **频繁忽略 context 导致多轮对话断裂**：在多轮会话中，务必正确维护和传递 context 信息。

## 四、与其他服务的集成要点

在实际开发中，QueryDTO 往往不是孤立使用的，它需要与 QnA Maker 客户端库的其他组件协同工作。例如，`QnAMakerRuntimeClient` 通过其 `queryMethod` 方法接收 QueryDTO 参数来完成查询。这一过程中，正确的参数序列化、API 版本兼容性都非常关键。对于并发较高的场景，还需注意请求限流和超时设置。

## 五、总结

Azure QnA Maker 的 QueryDTO 接口为开发者提供了一套既灵活又精细的知识库查询控制机制。通过合理配置各个可选属性，开发者可以根据具体业务场景实现从简单问答到多轮会话、从宽松搜索到严格过滤的多样化查询需求。熟练掌握这一接口，是构建高质量、个性化知识库应用的基础能力。在今后的项目实施中，建议工程师结合自身业务特点和用户反馈，持续调优各参数配置，使知识库服务发挥出最大价值。