샘플링
샘플링은 서버가 클라이언트를 통해 LLM 완성을 요청할 수 있게 하는 강력한 MCP 기능으로, 보안과 개인정보 보호를 유지하면서 정교한 에이전트 동작을 가능하게 합니다.
샘플링 동작 방식
샘플링 흐름은 다음 단계를 따릅니다:
- 서버가 클라이언트에
sampling/createMessage요청을 전송 - 클라이언트가 요청을 검토하고 수정할 수 있음
- 클라이언트가 LLM에서 샘플링
- 클라이언트가 완성을 검토
- 클라이언트가 결과를 서버에 반환
이 인간-루프(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 배열은 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
}
}모범 사례
샘플링을 구현할 때:
- 항상 명확하고 잘 구조화된 프롬프트 제공
- 텍스트와 이미지 내용을 적절하게 처리
- 합리적인 토큰 제한 설정
includeContext를 통해 관련 컨텍스트 포함- 사용하기 전에 응답 검증
- 오류를 우아하게 처리
- 샘플링 요청의 속도 제한 고려
- 예상되는 샘플링 동작 문서화
- 다양한 모델 매개변수로 테스트
- 샘플링 비용 모니터링
인간-루프 제어
샘플링은 인간 감독을 염두에 두고 설계되었습니다:
프롬프트용
- 클라이언트는 사용자에게 제안된 프롬프트를 표시해야 함
- 사용자는 프롬프트를 수정하거나 거부할 수 있어야 함
- 시스템 프롬프트는 필터링되거나 수정될 수 있음
- 컨텍스트 포함은 클라이언트에 의해 제어됨
완성용
- 클라이언트는 사용자에게 완성을 표시해야 함
- 사용자는 완성을 수정하거나 거부할 수 있어야 함
- 클라이언트는 완성을 필터링하거나 수정할 수 있음
- 사용자는 어떤 모델이 사용되는지 제어
보안 고려사항
샘플링을 구현할 때:
- 모든 메시지 내용 검증
- 민감한 정보 정화
- 적절한 속도 제한 구현
- 샘플링 사용량 모니터링
- 전송 중 데이터 암호화
- 사용자 데이터 개인정보 보호 처리
- 샘플링 요청 감사
- 비용 노출 제어
- 타임아웃 구현
- 모델 오류를 우아하게 처리
일반적인 패턴
에이전트 워크플로우
샘플링은 다음과 같은 에이전트 패턴을 가능하게 합니다:
- 리소스 읽기 및 분석
- 컨텍스트를 기반으로 결정 내리기
- 구조화된 데이터 생성
- 다단계 작업 처리
- 상호작용적 지원 제공
컨텍스트 관리
컨텍스트를 위한 모범 사례:
- 최소한의 필요한 컨텍스트 요청
- 컨텍스트를 명확하게 구조화
- 컨텍스트 크기 제한 처리
- 필요에 따라 컨텍스트 업데이트
- 오래된 컨텍스트 정리
오류 처리
강력한 오류 처리는 다음을 포함해야 합니다:
- 샘플링 실패 포착
- 타임아웃 오류 처리
- 속도 제한 관리
- 응답 검증
- 대체 동작 제공
- 오류를 적절하게 기록
제한사항
다음 제한사항을 인지하십시오:
- 샘플링은 클라이언트 기능에 의존
- 사용자가 샘플링 동작을 제어
- 컨텍스트 크기에는 제한이 있음
- 속도 제한이 적용될 수 있음
- 비용을 고려해야 함
- 모델 가용성은 다양함
- 응답 시간은 다양함
- 모든 콘텐츠 유형이 지원되는 것은 아님