MCP 官方文档中文版
  1. 概念
MCP 官方文档中文版
  • 开始使用
    • 简介
    • 示例 Servers
    • 示例 Clients
    • 快速上手
      • 服务器开发
      • 客户端开发
      • Claude 桌面版开发
  • 教程
    • 使用 LLMs 构建 MCP
    • 调试 Debugging
    • 调试器 Inspector
  • 概念
    • 核心架构
    • 资源 Resources
    • 提示词 Prompts
    • 工具 Tools
    • 采样 Sampling
    • 根 Roots
    • 传输 Transports
  • 开发
    • 新计划
    • 规划
    • 贡献
  1. 概念

采样 Sampling

让您的服务器请求来自 LLM 的补全#

采样 (Sampling) 是一项强大的 MCP 功能,它允许服务器通过客户端请求 LLM 完成,从而实现复杂的代理行为,同时保持安全性和隐私。
此 MCP 功能在 Claude 桌面客户端 (Claude Desktop client)中尚不支持。

采样的工作原理#

采样流程包括以下步骤:
1.
服务器向客户端发送 sampling/createMessage 请求
2.
客户端审核请求并可以修改它
3.
客户端从 LLM 采样
4.
客户端审核完成结果
5.
客户端将结果返回给服务器
这种人机协作的设计确保用户保持对 LLM 所见和所生成内容的控制。

消息格式#

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

请求参数#

消息#

messages 数组包含要发送到 LLM 的对话历史记录。 每条消息都有:
role: “user” 或 “assistant”
content
: 消息内容,可以是:
带有 text 字段的文本内容
带有 data(base64 编码)和 mimeType 字段的图像内容

模型偏好#

modelPreferences 对象允许服务器指定其模型选择偏好:
hints: 客户端可用于选择合适模型的模型名称建议数组:
name: 可以匹配完整或部分模型名称的字符串(例如,“claude-3”,“sonnet”)
客户端可以将提示(hints)映射到来自不同提供商的等效模型
多个提示(hints)按偏好顺序评估
优先级值(0-1 归一化):
costPriority: 最小化成本的重要性
speedPriority: 低延迟响应的重要性
intelligencePriority: 高级模型能力的重要性
客户端根据这些偏好及其可用模型进行最终模型选择。

系统提示#

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

上下文包含#

includeContext 参数指定要包含的 MCP 上下文:
"none":无其他上下文
"thisServer":包含来自请求服务器的上下文
"allServers":包含来自所有连接的 MCP 服务器的上下文
客户端控制实际包含哪些上下文。

采样参数#

使用以下方法微调 LLM 采样:
temperature: 控制随机性(0.0 到 1.0)
maxTokens: 要生成的最大令牌(token)数
stopSequences: 停止生成的序列数组
metadata: 其他特定于提供程序的参数

响应格式#

客户端返回一个完成结果:

示例请求#

以下是请求从客户端进行采样的示例:
{
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What files are in the current directory?"
        }
      }
    ],
    "systemPrompt": "You are a helpful file system assistant.",
    "includeContext": "thisServer",
    "maxTokens": 100
  }
}

最佳实践#

实施采样时:
1.
始终提供清晰、结构良好的提示(prompts)
2.
适当地处理文本和图像内容
3.
设置合理的令牌(token)限制
4.
通过 includeContext 包含相关上下文
5.
在使用响应之前对其进行验证
6.
优雅地处理错误
7.
考虑对采样请求进行速率限制(rate limiting)
8.
记录预期的采样行为
9.
使用各种模型参数进行测试
10.
监控采样成本

人机回路控制#

采样的设计考虑到了人工监督:

对于提示#

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

对于完成#

客户端应向用户显示完成结果
用户应该能够修改或拒绝完成结果
客户端可以过滤或修改完成结果
用户控制使用哪个模型

安全注意事项#

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

常见模式#

代理工作流#

采样支持诸如以下代理模式:
阅读和分析资源
根据上下文做出决策
生成结构化数据
处理多步骤任务
提供互动式帮助

上下文管理#

上下文的最佳实践:
请求最少的必要上下文
清晰地构建上下文
处理上下文大小限制
根据需要更新上下文
清理过时的上下文

错误处理#

强大的错误处理应:
捕获采样失败
处理超时错误
管理速率限制(rate limits)
验证响应
提供回退行为
适当地记录错误

局限性#

请注意以下限制:
采样取决于客户端功能
用户控制采样行为
上下文大小有限制
速率限制(rate limits)可能适用
应考虑成本
模型可用性各不相同
响应时间各不相同
并非支持所有内容类型

扫码加入 Apifox MCP 内测群

MCP生态正在快速发展,我们正在与开发者们一起探索 AI 和 API 协作的未来。

扫码加入交流群
上一页
工具 Tools
下一页
根 Roots
Built with