# 추론 커넥터 대상 추론 커넥터 대상은 지원되는 모델 공급자를 위해 미리 구성된 설정을 제공합니다. 커넥터를 사용하는 경우 게이트웨이는 공급자의 API에 대한 기본 지식을 기반으로 작업, 모델 검색, 모델 ID 번역 및 경로 재작성을 자동으로 처리하므로 수동으로 지정할 필요가 없습니다. 커넥터는 엔드포인트, 작업 또는 모델 매핑을 수동으로 구성하지 않고 지원되는 모델 공급자를 빠르게 추가하려는 경우에 권장됩니다. **Topics** + [대상 구성](#gateway-target-inference-connector-config) + [커넥터 추론 대상 생성](#gateway-target-inference-connector-create) + [커넥터 추론 대상 호출](#gateway-target-inference-connector-invoke) + [사용 가능한 모델 나열](#gateway-target-inference-connector-list-models) + [모델 기반 라우팅](#gateway-target-inference-connector-routing) + [스트리밍](#gateway-target-inference-connector-streaming) + [아웃바운드 권한 부여](#gateway-target-inference-connector-auth) ## 대상 구성 추론 커넥터 대상의 대상 구성은 다음 구조를 사용합니다. ``` { "inference": { "connector": { "source": { "connectorId": "bedrock-mantle" } } } } ``` + **connectorId**(필수) - 내장 커넥터의 식별자입니다. 지원되는 값은 `bedrock-mantle`, `openai` 및 `anthropic`입니다. 각 커넥터는 완전히 지정된 공급자 구성과 동일한 기본값을 제공합니다. 예를 들어 `bedrock-mantle` 커넥터는 다음을 자동으로 구성합니다. + **모델 ID 접두사 제거** - 클라이언트는 모델 IDs(예: `claude-opus-4-7` 대신 사용`anthropic.claude-opus-4-7`). + **경로 재작성** - 인바운드 추론 요청 경로는 공급자의 API 경로에 매핑됩니다. + **지원되는 작업** - 채팅 완료 및 메시지와 같이 커넥터가 노출하는 추론 작업 세트입니다. ## 커넥터 추론 대상 생성 다음 예제에서는 Bedrock Mantle 커넥터를 사용하여 추론 대상을 생성하는 방법을 보여줍니다. ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "bedrock-mantle", "targetConfiguration": { "inference": { "connector": { "source": { "connectorId": "bedrock-mantle" } } } }, "credentialProviderConfigurations": [ {"credentialProviderType": "GATEWAY_IAM_ROLE"} ] }' ``` 다음 예제에서는 OpenAI 커넥터를 사용하여 추론 대상을 생성하는 방법을 보여줍니다. ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "openai", "targetConfiguration": { "inference": { "connector": { "source": { "connectorId": "openai" } } } }, "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 " } } } ] }' ``` 다음 예제에서는 Anthropic 커넥터를 사용하여 추론 대상을 생성하는 방법을 보여줍니다. ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "anthropic", "targetConfiguration": { "inference": { "connector": { "source": { "connectorId": "anthropic" } } } }, "credentialProviderConfigurations": [ { "credentialProviderType": "API_KEY", "credentialProvider": { "apiKeyCredentialProvider": { "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/apikeycredentialprovider/anthropic-key", "credentialLocation": "HEADER", "credentialParameterName": "x-api-key" } } } ] }' ``` ## 커넥터 추론 대상 호출 추론 대상을 호출하려면 게이트웨이 `/inference` 경로로 요청을 보냅니다. 게이트웨이는 요청 본문의 `model` 필드를 기반으로 각 요청을 올바른 대상으로 라우팅합니다. `model` 값은 일반 모델 ID(예: `gpt-5.5`) 또는 형식의 대상 한정 모델 ID`{targetName}/{modelId}`(예: )일 수 있습니다`openai/gpt-5.5`. `model` 값이 대상과 일치하는 방법에 대한 자세한 내용은 [모델 기반 라우팅](#gateway-target-inference-connector-routing)을 참조하세요. URL 형식은 다음과 같습니다. ``` https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/inference/{path} ``` 를 추론 작업 경로(예: , `v1/responses`또는 `v1/chat/completions``v1/messages`)`{path}`로 바꿉니다. ### OpenAI SDK 사용 게이트웨이의 `/inference/v1` 경로를 로 설정합니다. `base_url` ``` from openai import OpenAI client = OpenAI( base_url="https://.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference/v1", api_key="" ) response = client.chat.completions.create( model="gpt-5.5", messages=[{"role": "user", "content": "Hello!"}] ) ``` ### Anthropic SDK 사용 게이트웨이의 `/inference` 경로를 로 설정합니다. `base_url` ``` import anthropic client = anthropic.Anthropic( base_url="https://.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference", api_key="" ) response = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, messages=[{"role": "user", "content": "Hello!"}] ) ``` ### awscurl 사용 ``` awscurl --service bedrock-agentcore --region us-west-2 -X POST \ "https://.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!"}]}' ``` ## 사용 가능한 모델 나열 모든 추론 대상에서 사용 가능한 모델을 검색하려면 모델 목록 엔드포인트를 호출합니다. ``` awscurl --service bedrock-agentcore --region us-west-2 \ "https://.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference/v1/models" ``` 응답은 OpenAI 형식이며 모델 ID `/v1/models` 앞에 대상 이름이 접두사로 붙습니다. IDs ``` { "data": [ {"id": "bedrock-mantle/anthropic.claude-opus-4-7", "object": "model", "owned_by": "system"}, {"id": "openai/gpt-5.5", "object": "model", "owned_by": "openai"}, {"id": "anthropic/claude-sonnet-4-6", "object": "model", "owned_by": "anthropic"} ] } ``` `owned_by` 필드는 모델의 공급자를 나타냅니다. 값은 Amazon Bedrock에서 호스팅하는 모델을 `system` 나타내는 반면, `openai` 및는 해당 공급자가 직접 제공하는 모델을 `anthropic` 나타냅니다. ## 모델 기반 라우팅 게이트웨이는 요청 본문의 `model` 필드를 기반으로 추론 요청을 라우팅합니다. 1. **정규화된 라우팅** - 모델 ID에가 포함되어 `/` 있고 접두사가 대상 이름과 일치하는 경우 요청이 해당 대상으로 라우팅됩니다(예: `openai` 대상으로 `openai/gpt-5.5` 라우팅). 1. **정규화되지 않은 라우팅** - 모델 ID에가 포함되지 않은 경우 `/`게이트웨이는 구성된 모든 대상과 일치시킵니다. 정확한 일치는 glob 패턴보다 우선합니다. 정확히 하나의 대상이 일치하면 요청이 해당 대상으로 라우팅됩니다. 1. **충돌 처리** - 여러 대상이 동일한 특이도로 동일한 모델과 일치하면 일치 항목 중 하나인 경우 게이트웨이는 기본적으로 Amazon Bedrock 대상으로 설정됩니다. 그렇지 않으면 각 요청에서 일치하는 대상 중 하나를 무작위로 선택하므로 동일한 모델에 대한 요청이 서로 다른 대상에 도달할 수 있습니다. 요청을 특정 대상에 고정하려면 대상 이름을 접두사로 사용하여 모델을 검증합니다(예: `bedrock/claude-opus-4-7`). ## 스트리밍 스트리밍은 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="") ``` ### 응답 스트림 제한 **중요** AgentCore Gateway는 응답 스트림 기간 또는 응답 크기에 서비스 수준 최대값을 적용하지 않습니다. 게이트웨이 대상에 토큰 제한 정책을 구성하지 않으면 각 요청이 무제한 스트리밍 응답을 생성할 수 있습니다. 토큰 제한 정책을 구성하지 않으면 무제한 응답으로 인해 다음과 같은 문제가 발생할 수 있습니다. + **게이트웨이 리소스 소진** - 게이트웨이는 각 스트리밍 응답 기간 동안 컴퓨팅 리소스(메모리, HTTP 연결 풀 슬롯 및 정책 평가를 위한 CPU)를 열어 둡니다. 대규모 동시 스트림은 게이트웨이 작업 리소스를 소진할 수 있습니다. + **공유 자격 증명에 대한 비용 증폭** - 동일한 대상을 통해 라우팅하는 모든 사용자는 한 세트의 공급자 자격 증명을 공유합니다. 높은`max_tokens` 요청을 보내는 단일 사용자는 해당 대상의 모든 사용자에 대해 공급자의 tokens-per-minute(TPM) 할당량을 사용할 수 있습니다. + **노이즈가 많은 이웃 효과** Requests-per-minute(RPM) 조절은 요청 수를 제한하지만 요청당 비용은 제한하지 않습니다. 단일 사용자는 RPM 한도 내에서 최대 비용 요청을 생성하여 다른 사용자의 성능을 저하시킬 수 있습니다. 이러한 위험을 완화하려면 게이트웨이 대상에 토큰 제한 정책을 구성합니다. 자세한 내용은 [게이트웨이 정책을](gateway-policies.html) 참조하세요. ## 아웃바운드 권한 부여 추론 커넥터 대상은 다음과 같은 아웃바운드 권한 부여 유형을 지원합니다. + **IAM(SigV4)** - IAM 인증을 수락하는 공급자(예: Amazon Bedrock)`GATEWAY_IAM_ROLE`에 사용합니다. + **API 키** - API 키(예: OpenAI 및 Anthropic)가 필요한 공급자`API_KEY`에 사용합니다. 게이트웨이는 저장된 API 키를 아웃바운드 요청에 주입합니다.