Sampling - 采样

让服务器向 LLM 请求补全

采样（Sampling） 是 MCP（模型上下文协议，Model Context Protocol） 的一个强大功能，它允许服务器通过客户端请求 LLM 补全（completions），从而实现复杂的智能代理行为，同时保持安全性和隐私性。

注意：当前 Claude Desktop 客户端尚不支持此功能。

采样工作原理

采样流程包括以下步骤：

1. 服务器 向客户端发送 sampling/createMessage 请求。
2. 客户端 审查请求并可进行修改。
3. 客户端 通过 LLM 进行采样。
4. 客户端 审查生成的补全内容。
5. 客户端 将结果返回给服务器。

此 人工审核（human-in-the-loop） 设计确保用户始终掌控 LLM 所接收和生成的内容。

消息格式

采样请求使用标准化的消息格式：

{
  messages: [
    {
      role: "user" | "assistant",
      content: {
        type: "text" | "image",
        // 文本内容：
        text?: string,
        // 图片内容：
        data?: string,             // base64 编码
        mimeType?: string
      }
    }
  ],
  modelPreferences?: {
    hints?: [{
      name?: string                // 建议的模型名称/系列
    }],
    costPriority?: number,         // 0-1，成本优先级
    speedPriority?: number,        // 0-1，速度优先级
    intelligencePriority?: number  // 0-1，智能能力优先级
  },
  systemPrompt?: string,
  includeContext?: "none" | "thisServer" | "allServers",
  temperature?: number,
  maxTokens: number,
  stopSequences?: string[],
  metadata?: Record<string, unknown>
}

请求参数解析

消息（Messages）

messages 数组包含要发送给 LLM 的对话历史，每条消息包括：

• role：消息的角色，值可以是 "user"（用户）或 "assistant"（助手）。
• content：消息内容，可以是：
  • 文本内容（text 字段）。
  • 图片内容（data，Base64 编码；mimeType，MIME 类型）。

模型偏好（Model Preferences）

modelPreferences 允许服务器指定 LLM 选择偏好：

• 模型名称提示（hints）：

  • name：建议的模型名称，可使用完整或部分名称（例如 "claude-3"、"sonnet"）。
  • 客户端可以将提示映射到不同提供商的等效模型。
  • 多个提示按优先顺序评估。

• 优先级参数（0-1 之间的值，归一化）：

  • costPriority：成本控制的优先级。
  • speedPriority：低延迟优先级。
  • intelligencePriority：模型智能能力的优先级。

最终模型选择由客户端决定，服务器仅提供偏好建议。

系统提示（System Prompt）

可选的 systemPrompt 字段允许服务器请求特定的系统提示（system prompt），但客户端可能会修改或忽略该提示。

上下文包含（Context Inclusion）

includeContext 参数指定是否包含 MCP 上下文：

• "none"：不包含任何额外上下文。
• "thisServer"：仅包含当前服务器的上下文。
• "allServers"：包含所有已连接 MCP 服务器的上下文。

客户端决定实际包含的上下文。

采样参数（Sampling Parameters）

用于控制 LLM 采样行为的参数：

• temperature：控制生成的随机性（0.0 到 1.0）。
• maxTokens：生成的最大 token 数。
• stopSequences：用于停止生成的字符串数组。
• metadata：额外的特定提供商参数。

响应格式

客户端返回的补全结果格式如下：

{
  model: string,  // 使用的模型名称
  stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string,
  role: "user" | "assistant",
  content: {
    type: "text" | "image",
    text?: string,
    data?: string,
    mimeType?: string
  }
}

采样请求示例

以下示例展示了如何请求客户端进行采样：

{
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "当前目录下有哪些文件？"
        }
      }
    ],
    "systemPrompt": "你是一个有帮助的文件系统助手。",
    "includeContext": "thisServer",
    "maxTokens": 100
  }
}

最佳实践

1. 提供清晰、结构化的提示。
2. 正确处理文本和图片内容。
3. 设置合理的 token 限制，防止超长生成。
4. 使用 includeContext 提供相关上下文，避免上下文丢失。
5. 验证 LLM 生成的响应，确保安全性。
6. 优雅地处理错误，避免崩溃或异常情况。
7. 对采样请求进行速率限制，防止滥用。
8. 记录和文档化采样行为，方便调试。
9. 使用不同模型参数进行测试，优化效果。
10. 监控采样成本，避免超支。

人工审核控制（Human-in-the-loop Controls）

采样流程包含用户审核机制：

对提示（Prompts）

• 客户端应向用户展示建议的提示。
• 用户可修改或拒绝提示。
• 系统提示（system prompt）可被过滤或修改。
• 上下文包含（includeContext）由客户端控制。

对补全（Completions）

• 客户端应向用户展示 LLM 生成的内容。
• 用户可以修改或拒绝生成的补全。
• 客户端可过滤或修改补全内容。
• 用户控制所使用的模型。

安全考虑（Security Considerations）

在实现采样功能时，需要关注以下安全问题：

• 验证所有消息内容，防止恶意输入。
• 对敏感信息进行清理和保护，防止数据泄露。
• 实施合理的速率限制，避免资源滥用。
• 监控采样使用情况，防止异常行为。
• 确保数据传输加密，保护用户隐私。
• 正确处理用户数据隐私，符合合规要求。
• 记录和审计采样请求，以备后续分析。
• 控制成本风险，防止 API 费用过高。
• 设置合理的超时，避免长时间等待。
• 优雅处理 LLM 生成错误，提供回退策略。

常见模式

智能代理（Agentic Workflows）

采样功能支持智能代理模式，如：

• 分析资源并提供建议。
• 基于上下文进行决策。
• 生成结构化数据。
• 处理多步骤任务。
• 提供交互式帮助。

上下文管理（Context Management）

• 仅请求 最少必要的上下文。
• 结构化地组织上下文。
• 控制上下文大小限制。
• 动态更新上下文。
• 清理过时的上下文。

错误处理（Error Handling）

• 捕获采样失败的情况。
• 处理超时错误。
• 管理速率限制。
• 验证 LLM 响应内容。
• 提供回退机制。
• 记录错误日志。

限制（Limitations）

• 依赖于客户端能力。
• 用户对采样行为有最终控制权。
• 上下文大小有限制。
• 可能存在速率限制。
• 需要考虑 API 成本。
• 模型可用性可能有所不同。
• 响应时间可能有所波动。
• 并非所有内容类型都受支持。