Dynamic header substitution

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

동적 헤더 대체

3.7 버전에서 도입됨 {: .label .label-purple }

기본적으로 커넥터 헤더는 커넥터 생성 시 한 번 해석됩니다. 동적 커넥터 헤더를 사용하면 헤더 값에 ${parameters.*} 자리 표시자를 사용하여 예측 시 요청별 값이 대체되도록 할 수 있습니다. 이는 트랜잭션 ID, 상관관계 ID 또는 추적 토큰과 같은 요청 범위 메타데이터를 외부 호스팅 모델 엔드포인트에 전달하는 데 유용합니다.

동적 헤더 구성

동적 헤더를 구성하려면 커넥터의 actions[].headers 필드에 ${parameters.*} 자리 표시자를 사용하여 헤더를 정의합니다. 선택적으로 최상위 parameters 필드에서 매개변수의 기본값을 설정할 수 있습니다.

POST /_plugins/_ml/connectors/_create
{
  "name": "My connector",
  "description": "Connector with dynamic headers",
  "version": 1,
  "protocol": "http",
  "parameters": {
    "endpoint": "api.example.com",
    "request_id": "default-request-id"
  },
  "credential": {
    "api_key": "test-api-key"
  },
  "actions": [{
    "action_type": "predict",
    "method": "POST",
    "url": "https://${parameters.endpoint}/predict",
    "headers": {
      "Authorization": "${credential.api_key}",
      "X-Test-Request-Id": "${parameters.request_id}"
    },
    "request_body": "{ \"input\": \"${parameters.input}\" }"
  }]
}

{% include copy-curl.html %}

예측 시 _predict 요청의 parameters 필드에 런타임 값을 전달합니다.

POST /_plugins/_ml/models/{model_id}/_predict
{
  "parameters": {
    "request_id": "request-123",
    "input": "hello world"
  }
}

{% include copy-curl.html %}

결과적으로 원격 엔드포인트에 대한 HTTP 요청에는 대체된 헤더가 포함됩니다.

POST https://api.example.com/predict
Authorization: test-api-key
X-Test-Request-Id: request-123

런타임 값이 제공되지 않고 커넥터의 parameters 필드에 기본값이 설정되지 않은 경우 예측 요청은 400 오류와 함께 거부됩니다. 이를 방지하려면 커넥터의 parameters 필드에 매개변수의 기본값을 정의하세요. 런타임 값이 제공되지 않으면 기본값이 사용됩니다.

보안 제한 사항

다음 헤더는 ${parameters.*} 자리 표시자를 포함할 수 없습니다. 이를 사용하면 커넥터 생성 또는 업데이트 시 400 오류가 반환됩니다. 대신 인증 헤더에는 ${credential.*}를 사용하세요.

자격 증명 헤더:
- Authorization
- Proxy-Authorization
- Cookie
- X-API-Key
- X-Auth-Token
- X-Auth-Header
IP 및 호스트 스푸핑 헤더:
- Host
- X-Forwarded-Host
- X-Forwarded-Server
- X-Forwarded-For
- Forwarded
- X-Real-IP
- X-Client-IP
- CF-Connecting-IP
- True-Client-IP
- X-Originating-IP

런타임 검증

예측 시 대체된 헤더 값은 요청이 전송되기 전에 검증됩니다.

HTTP 응답 분할을 방지하기 위해 \r 또는 \n 문자가 포함된 헤더 값은 거부됩니다.
제어 문자(0x00–0x1F, 탭 제외)가 포함된 값은 거부됩니다.
각 개별 헤더 값은 8KB를 초과할 수 없습니다.
모든 헤더의 총 크기는 64KB를 초과할 수 없습니다.

다음 단계

모든 커넥터 필드에 대한 설명은 커넥터 청사진을 참조하세요.
커넥터에 인증 자격 증명을 제공하는 방법에 대한 자세한 내용은 커넥터 인증에서 플랫폼 프로토콜에 대한 인증 방법을 참조하세요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/ml-commons-plugin/remote-models/dynamic-header-substitution/