采样#

采样是 MCP 的一项强大功能，允许服务器通过客户端请求大型语言模型（LLM）的完成，从而实现复杂的代理行为，同时保持安全性和隐私。

采样工作原理#

采样流程遵循以下步骤：

1. 服务器向客户端发送 sampling/createMessage 请求
2. 客户端审查请求并可对其进行修改
3. 客户端从 LLM 进行采样
4. 客户端审查完成结果
5. 客户端将结果返回给服务器

这种“人在回路中”的设计确保用户对 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 数组包含发送给 LLM 的对话历史记录。每条消息包括：

• role：可以是 "user" 或 "assistant"
• content：消息内容，可以是：
  • 包含 text 字段的文本内容
  • 包含 data（base64 编码）和 mimeType 字段的图像内容

模型偏好#

modelPreferences 对象允许服务器指定模型选择偏好：

• hints：模型名称建议数组，客户端可用于选择合适的模型：

  • name：可以匹配完整或部分模型名称的字符串（例如 "claude-3"、"sonnet"）
  • 客户端可能将提示映射到不同提供商的等效模型
  • 多个提示按优先级顺序评估

• 优先级值（0-1 归一化）：

  • costPriority：降低成本的重要性
  • speedPriority：低延迟响应的重视程度
  • intelligencePriority：高级模型能力的重要性

客户端根据这些偏好及其可用模型进行最终模型选择。

系统提示#

可选的 systemPrompt 字段允许服务器请求特定的系统提示。客户端可以修改或忽略此提示。

上下文包含#

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

• "none"：不包含额外上下文
• "thisServer"：包含请求服务器的上下文
• "allServers"：包含所有连接的 MCP 服务器的上下文

客户端控制实际包含的上下文。

采样参数#

通过以下参数微调 LLM 采样：

• temperature：控制随机性（0.0 到 1.0）
• maxTokens：生成的最大令牌数
• 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. 设置合理的令牌限制
4. 通过 includeContext 包含相关上下文
5. 在使用前验证响应
6. 优雅处理错误
7. 考虑对采样请求设置速率限制
8. 记录预期的采样行为
9. 使用各种模型参数进行测试
10. 监控采样成本

人在回路中的控制#

采样设计时考虑了人工监督：

对于提示#

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

对于完成#

• 客户端应向用户展示完成结果
• 用户应能修改或拒绝完成结果
• 客户端可以过滤或修改完成结果
• 用户控制使用的模型

安全考虑#

实现采样时：

• 验证所有消息内容
• 清理敏感信息
• 实施适当的速率限制
• 监控采样使用情况
• 传输中加密数据
• 处理用户数据隐私
• 审计采样请求
• 控制成本暴露
• 实施超时
• 优雅处理模型错误

常见模式#

代理工作流#

采样支持代理模式，例如：

• 阅读和分析资源
• 根据上下文作出决策
• 生成结构化数据
• 处理多步骤任务
• 提供交互式协助

上下文管理#

上下文的最佳实践：

• 请求最少必要的上下文
• 清晰结构化上下文
• 处理上下文大小限制
• 根据需要更新上下文
• 清理过时的上下文

错误处理#

稳健的错误处理应：

• 捕获采样失败
• 处理超时错误
• 管理速率限制
• 验证响应
• 提供回退行为
• 适当记录错误

限制#

需注意以下限制：

• 采样依赖于客户端能力
• 用户控制采样行为
• 上下文大小有限制
• 可能适用速率限制
• 需考虑成本
• 模型可用性各异
• 响应时间各异
• 并非所有内容类型都受支持