> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.transdocs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 采样

<Info>**协议修订**: 2024-11-05</Info>

模型上下文协议（MCP）为服务器通过客户端从语言模型请求LLM采样（“补全”或“生成”）提供了标准化方式。此流程允许客户端控制模型的访问、选择和权限，同时使服务器能够利用AI能力——无需服务器API密钥。
服务器可以请求文本或基于图像的交互，并可选地在其提示中包含来自MCP服务器的上下文。

## 用户交互模型

MCP中的采样允许服务器实现代理行为，通过在其他MCP服务器功能内部嵌套LLM调用。

实现可以自由地通过任何适合其需求的界面模式暴露采样功能——协议本身不规定任何特定的用户交互模型。

<Warning>
  出于信任、安全和保障目的，**必须**始终有具备拒绝采样请求能力的人类参与其中。

  应用程序**应该**：

  * 提供易于审查采样请求的UI
  * 允许用户在发送前查看和编辑提示
  * 在交付前呈现生成的响应以供审查
</Warning>

## 能力

支持采样的客户端**必须**在[初始化](/specification/2024-11-05/basic/lifecycle#initialization)期间声明`sampling`能力：

```json theme={null}
{
  "capabilities": {
    "sampling": {}
  }
}
```

## 协议消息

### 创建消息

要请求语言模型生成，服务器发送`sampling/createMessage`请求：

**请求：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "法国的首都是哪里？"
        }
      }
    ],
    "modelPreferences": {
      "hints": [
        {
          "name": "claude-3-sonnet"
        }
      ],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5
    },
    "systemPrompt": "你是一个有帮助的助手。",
    "maxTokens": 100
  }
}
```

**响应：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "法国的首都是巴黎。"
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}
```

## 消息流

```mermaid theme={null}
sequenceDiagram
    participant Server
    participant Client
    participant User
    participant LLM

    Note over Server,Client: 服务器发起采样
    Server->>Client: sampling/createMessage

    Note over Client,User: 人类参与审查
    Client->>User: 显示请求以供批准
    User-->>Client: 审查并批准/修改

    Note over Client,LLM: 模型交互
    Client->>LLM: 转发已批准的请求
    LLM-->>Client: 返回生成结果

    Note over Client,User: 响应审查
    Client->>User: 显示响应以供批准
    User-->>Client: 审查并批准/修改

    Note over Server,Client: 完成请求
    Client-->>Server: 返回已批准的响应
```

## 数据类型

### 消息

采样消息可以包含：

#### 文本内容

```json theme={null}
{
  "type": "text",
  "text": "消息内容"
}
```

#### 图像内容

```json theme={null}
{
  "type": "image",
  "data": "base64编码的图像数据",
  "mimeType": "image/jpeg"
}
```

### 模型偏好

MCP中的模型选择需要仔细抽象，因为服务器和客户端可能使用具有不同模型产品的不同AI提供商。服务器不能简单地按名称请求特定模型，因为客户端可能无法访问该精确模型，或者可能更愿意使用其他提供商的等效模型。

为了解决这个问题，MCP实现了一个偏好系统，结合了抽象的能力优先级和可选的模型提示：

#### 能力优先级

服务器通过三个标准化的优先级值（0-1）表达其需求：

* `costPriority`：成本最小化有多重要？较高值偏好更便宜的模型。
* `speedPriority`：低延迟有多重要？较高值偏好更快的模型。
* `intelligencePriority`：高级功能有多重要？较高值偏好更有能力的模型。

#### 模型提示

虽然优先级有助于根据特征选择模型，但`hints`允许服务器建议特定模型或模型系列：

* 提示被视为可以灵活匹配模型名称的子字符串
* 多个提示按偏好顺序评估
* 客户端**可以**将提示映射到不同提供商的等效模型
* 提示是建议性的——客户端进行最终模型选择

例如：

```json theme={null}
{
  "hints": [
    { "name": "claude-3-sonnet" }, // 偏好Sonnet类模型
    { "name": "claude" } // 回退到任何Claude模型
  ],
  "costPriority": 0.3, // 成本不太重要
  "speedPriority": 0.8, // 速度非常重要
  "intelligencePriority": 0.5 // 中等能力需求
}
```

客户端处理这些偏好，从其可用选项中选择适当的模型。例如，如果客户端无法访问Claude模型但有Gemini，它可以根据类似能力将sonnet提示映射到`gemini-1.5-pro`。

## 错误处理

客户端**应该**为常见的失败情况返回错误：

示例错误：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -1,
    "message": "用户拒绝了采样请求"
  }
}
```

## 安全考虑

1. 客户端**应该**实现用户审批控制
2. 双方**应该**验证消息内容
3. 客户端**应该**尊重模型偏好提示
4. 客户端**应该**实现速率限制
5. 双方**必须**适当处理敏感数据