Skip to Content
文档概念采样

采样

让您的服务端通过客户端请求LLM的补全

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

此功能目前尚未在Claude桌面客户端中支持。

​ 采样的工作原理

采样的流程如下：

  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：生成的最大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. 在使用之前验证响应
  6. 优雅地处理错误
  7. 考虑对采样请求进行速率限制
  8. 记录预期的采样行为
  9. 使用各种模型参数进行测试
  10. 监控采样成本

​ 人在回路控制

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

​

对于提示

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

​

对于补全

  • 客户端应向用户显示补全结果
  • 用户应能够修改或拒绝补全结果
  • 客户端可以过滤或修改补全结果
  • 用户控制使用的模型

​ 安全注意事项

在实现采样时：

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

​ 常见模式

​

代理工作流

采样支持以下代理模式：

  • 读取和分析资源
  • 基于上下文做出决策
  • 生成结构化数据
  • 处理多步骤任务
  • 提供交互式帮助

​

上下文管理

上下文的最佳实践：

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

​

错误处理

健壮的错误处理应：

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

​ 限制

请注意以下限制：

  • 采样依赖于客户端的能力
  • 用户控制采样行为
  • 上下文大小有限制
  • 可能适用速率限制
  • 应考虑成本
  • 模型可用性不同
  • 响应时间不同
  • 并非所有内容类型都受支持
最后更新于:
提示根