# 추론 공급자 대상
<a name="gateway-target-inference-provider"></a>

추론 공급자 대상을 사용하면 모델 공급자의 엔드포인트, 모델 매핑 및 작업을 명시적으로 제어할 수 있습니다. 사용 가능한 모델을 사용자 지정하거나, 모델별 토큰 제한을 설정하거나, 경로 재작성을 구성하거나, 기본 제공 커넥터가 없는 공급자에 연결해야 하는 경우 공급자 구성을 사용합니다.

**Topics**
+ [대상 구성](#gateway-target-inference-provider-config)
+ [공급자 추론 대상 생성](#gateway-target-inference-provider-create)
+ [공급자 추론 대상 호출](#gateway-target-inference-provider-invoke)
+ [모델 기반 라우팅](#gateway-target-inference-provider-routing)
+ [스트리밍](#gateway-target-inference-provider-streaming)
+ [아웃바운드 권한 부여](#gateway-target-inference-provider-auth)

## 대상 구성
<a name="gateway-target-inference-provider-config"></a>

추론 공급자 대상의 대상 구성은 다음 구조를 사용합니다.

```
{
    "inference": {
        "provider": {
            "endpoint": "https://api.openai.com",
            "operations": [
                {
                    "path": "/v1/chat/completions",
                    "models": [
                        {"model": "gpt-5.5"},
                        {"model": "gpt-5.4"},
                        {"model": "gpt-5.4-mini"}
                    ]
                },
                {
                    "path": "/v1/responses",
                    "models": [
                        {"model": "gpt-5.5"},
                        {"model": "gpt-5.4"}
                    ]
                }
            ]
        }
    }
}
```
+  **엔드포인트**(필수) - 모델 공급자의 HTTPS URL입니다.
+  **modelMapping**(선택 사항) - 모델 ID 번역 구성입니다.
  +  **providerPrefix**(선택 사항) - 클라이언트가 모델 IDs에서 공급자 접두사를 생략하는 방법을 구성합니다. 생략하면 접두사 번역이 적용되지 않으며 클라이언트는 공급자의 전체 모델 IDs를 사용해야 합니다.
    +  **strip**(선택 사항) - 인 경우 `true`클라이언트는 공급자 접두사 없이 모델 IDs를 사용할 수 있습니다(예: `claude-opus-4-7` 대신 `anthropic.claude-opus-4-7`). 기본값은 `false`입니다.
    +  **구분자**(선택 사항) - 공급자 접두사와 모델 이름 사이의 구분자 문자입니다(예: `.`).
+  **작업**(선택 사항) - 요청 경로를 지원되는 모델에 매핑하는 작업 구성 목록입니다.
  +  **path**(필수) -이 작업의 요청 경로입니다(예: `/v1/chat/completions`).
  +  **providerPath**(선택 사항) - 요청 경로와 다른 경우 공급자의에 전달할 경로입니다.
  +  **모델**(선택 사항) -이 작업에 지원되는 모델입니다. 각 항목에는 **모델** ID 또는 glob 패턴(예: )이 포함된 모델 필드(필수)가 포함됩니다`anthropic.claude-opus-*`.

## 공급자 추론 대상 생성
<a name="gateway-target-inference-provider-create"></a>

다음 예제에서는 공급자 구성을 사용하여 OpenAI 추론 대상을 생성합니다.

```
aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "openai",
    "targetConfiguration": {
        "inference": {
            "provider": {
                "endpoint": "https://api.openai.com",
                "operations": [
                    {
                        "path": "/v1/chat/completions",
                        "models": [
                            {"model": "gpt-5.5"},
                            {"model": "gpt-5.4"},
                            {"model": "gpt-5.4-mini"}
                        ]
                    },
                    {
                        "path": "/v1/responses",
                        "models": [
                            {"model": "gpt-5.5"},
                            {"model": "gpt-5.4"}
                        ]
                    }
                ]
            }
        }
    },
    "credentialProviderConfigurations": [
        {
            "credentialProviderType": "API_KEY",
            "credentialProvider": {
                "apiKeyCredentialProvider": {
                    "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/apikeycredentialprovider/openai-key",
                    "credentialLocation": "HEADER",
                    "credentialParameterName": "Authorization",
                    "credentialPrefix": "Bearer "
                }
            }
        }
    ]
}'
```

다음 예제에서는 명시적 공급자 구성 및 모델 매핑을 사용하여 Bedrock 추론 대상을 생성합니다. 를 사용한 `modelMapping` 구성을 `providerPrefix` 통해 클라이언트는 짧은 모델 이름(예: `claude-opus-4-7`)을 사용할 수 있지만 게이트웨이는 이를 공급자 접두사 이름(예`anthropic.claude-opus-4-7`: )으로 변환합니다.

```
aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "bedrock",
    "targetConfiguration": {
        "inference": {
            "provider": {
                "endpoint": "https://bedrock-mantle.us-east-1.api.aws",
                "modelMapping": {
                    "providerPrefix": {"strip": true, "separator": "."}
                },
                "operations": [
                    {
                        "path": "/v1/chat/completions",
                        "models": [
                            {"model": "anthropic.claude-opus-*"},
                            {"model": "anthropic.claude-sonnet-*"},
                            {"model": "openai.gpt-oss-*"}
                        ]
                    },
                    {
                        "path": "/v1/messages",
                        "providerPath": "/anthropic/v1/messages",
                        "models": [
                            {"model": "anthropic.claude-opus-*"},
                            {"model": "anthropic.claude-sonnet-*"}
                        ]
                    }
                ]
            }
        }
    },
    "credentialProviderConfigurations": [
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ]
}'
```

## 공급자 추론 대상 호출
<a name="gateway-target-inference-provider-invoke"></a>

추론 대상을 호출하려면 게이트웨이 `/inference` 경로로 요청을 보냅니다. 게이트웨이는 요청 본문의 `model` 필드를 기반으로 각 요청을 올바른 대상으로 라우팅합니다. `model` 값은 일반 모델 ID(예: `gpt-5.5`) 또는 형식의 대상 한정 모델 ID`{targetName}/{modelId}`(예: )일 수 있습니다`openai/gpt-5.5`. `model` 값이 대상과 일치하는 방법에 대한 자세한 내용은 [모델 기반 라우팅](#gateway-target-inference-provider-routing)을 참조하세요.

URL 형식은 다음과 같습니다.

```
https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/inference/{path}
```

를 추론 작업 경로(예: , `v1/responses`또는 `v1/chat/completions``v1/messages`)`{path}`로 바꿉니다.

### OpenAI SDK 사용
<a name="_using_the_openai_sdk"></a>

게이트웨이의 `/inference/v1` 경로를 로 설정합니다. `base_url` 

```
from openai import OpenAI

client = OpenAI(
    base_url="https://<gateway-id>.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference/v1",
    api_key="<gateway-auth-token>"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### Anthropic SDK 사용
<a name="_using_the_anthropic_sdk"></a>

게이트웨이의 `/inference` 경로를 로 설정합니다. `base_url` 

```
import anthropic

client = anthropic.Anthropic(
    base_url="https://<gateway-id>.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference",
    api_key="<gateway-auth-token>"
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### awscurl 사용
<a name="_using_awscurl"></a>

```
awscurl --service bedrock-agentcore --region us-west-2 -X POST \
    "https://<gateway-id>.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -d '{"model": "gpt-5.5", "messages": [{"role": "user", "content": "Hello!"}]}'
```

### 적격 모델 라우팅
<a name="_qualified_model_routing"></a>

여러 대상이 동일한 모델을 제공하는 경우 모델 ID에 특정 공급자로 라우팅할 대상 이름을 접두사로 붙입니다.

```
# Route explicitly to the "bedrock" target
response = client.chat.completions.create(
    model="bedrock/claude-opus-4-7",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

## 모델 기반 라우팅
<a name="gateway-target-inference-provider-routing"></a>

게이트웨이는 요청 본문의 `model` 필드를 기반으로 추론 요청을 라우팅합니다.

1.  **정규화된 라우팅** - 모델 ID에가 포함되어 `/` 있고 접두사가 대상 이름과 일치하는 경우 요청이 해당 대상으로 라우팅됩니다(예: `openai` 대상으로 `openai/gpt-5.5` 라우팅).

1.  **정규화되지 않은 라우팅** - 모델 ID에가 포함되지 않은 경우 `/`게이트웨이는 구성된 모든 대상과 일치시킵니다. 정확한 일치는 glob 패턴보다 우선합니다. 정확히 하나의 대상이 일치하면 요청이 해당 대상으로 라우팅됩니다.

1.  **충돌 처리** - 여러 대상이 동일한 특이도로 동일한 모델과 일치하면 일치 항목 중 하나인 경우 게이트웨이는 기본적으로 Amazon Bedrock 대상으로 설정됩니다. 그렇지 않으면 일치하는 대상 간에 요청을 라운드 로빈 순서로 분산합니다. 요청을 특정 대상에 고정하려면 대상 이름을 접두사로 사용하여 모델을 검증합니다(예: `bedrock/claude-opus-4-7`).

## 스트리밍
<a name="gateway-target-inference-provider-streaming"></a>

스트리밍은 OpenAI SSE 규칙을 따릅니다. 요청 본문`"stream": true`에를 설정하면 게이트웨이가 변환 없이 공급자의 SSE 스트림을 통과합니다.

```
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a story."}],
    stream=True
)

for chunk in stream:
    print(chunk.choices[0].delta.content, end="")
```

## 아웃바운드 권한 부여
<a name="gateway-target-inference-provider-auth"></a>

추론 공급자 대상은 다음과 같은 아웃바운드 권한 부여 유형을 지원합니다.
+  **IAM(SigV4)** - IAM 인증을 수락하는 공급자(예: Amazon Bedrock)`GATEWAY_IAM_ROLE`에 사용합니다.
+  **API 키** - API 키(예: OpenAI 및 Anthropic)가 필요한 공급자`API_KEY`에 사용합니다. 게이트웨이는 저장된 API 키를 아웃바운드 요청에 주입합니다.