모델 스트림 예측 API

모델 스트림 예측 API (Predict Model Stream API) (gRPC)

3.8에서 도입되었어요. gRPC Predict Model Stream API는 gRPC를 통해 프로토콜 버퍼를 사용해 원격 머신러닝(ML) 모델에서 예측을 스트리밍하는 이진 인터페이스를 제공해요. 기본 모델이 출력을 생성할 때 서버가 응답 청크를 클라이언트로 스트리밍하므로, 클라이언트는 추론이 끝나기 전에 출력 처리를 시작할 수 있어요. 대규모 언어 모델(LLM)에서 토큰 단위로 생성할 때는 스트리밍을 사용하세요.

예측은 REST 또는 gRPC로 스트리밍할 수 있어요. 두 전송 모두 같은 증분 생성 모델 출력을 반환하므로 클라이언트에 가장 잘 맞는 것을 선택하세요.

REST 스트리밍은 HTTP 위의 서버 전송 이벤트(SSE)를 사용하는데, 브라우저, 표준 HTTP 클라이언트, cURL 같은 명령줄 도구가 직접 지원해요. 이 기능은 실험적이며 프로덕션 환경에서의 사용은 권장되지 않아요. 자세한 내용은 Predict Stream API를 참고하세요.
gRPC 스트리밍은 HTTP/2 위의 프로토콜 버퍼를 사용해요. 이 전송은 더 낮은 직렬화 오버헤드와 더 작은 페이로드, HTTP/2 흐름 제어와 연결 멀티플렉싱을 통한 네이티브 서버 스트리밍 의미론, 그리고 gRPC가 지원하는 어떤 언어로든 클라이언트를 생성할 수 있는 강력한 타입의 스키마를 제공해요.

스트리밍 예측은 다음 외부 호스팅 모델에 대해 지원돼요.

OpenAI Chat Completion
Amazon Bedrock Converse Stream

출처: 문서

본문

사전 요구 사항 (Prerequisites)

gRPC Predict Model Stream API를 사용하기 전에 다음 사전 요구 사항을 충족했는지 확인하세요.

클러스터에서 gRPC 전송을 활성화해요. 자세한 내용은 Using gRPC APIs를 참고하세요.
클라이언트 쪽에서 ML Commons protobuf를 확보해요. protobuf를 얻는 방법은 Using gRPC APIs를 참고하세요.
지원되는 모델 유형에 대해 외부 호스팅 모델과 스트리밍 커넥터를 구성해요. 모델과 커넥터 구성은 Predict Stream API를 참고하세요.

gRPC 서비스와 메서드 (gRPC service and method)

gRPC Predict Model Stream API는 MLService 서비스에 있어요.

MLService 안의 PredictModelStream 메서드를 호출해서 스트리밍 예측 요청을 제출할 수 있어요. 이 메서드는 MlPredictModelStreamRequest를 받아 PredictResponse 메시지의 스트림을 반환해요.

PredictModelStream은 서버 스트리밍 원격 프로시저 호출(RPC)이에요. 클라이언트가 단일 요청을 보내면 서버가 일련의 응답 메시지를 반환해요. 마지막 메시지는 is_last를 true로 설정하고, 서버는 그 후 스트림을 닫아요.

요청 필드 (Request fields)

gRPC Predict Model Stream API는 다음 요청 필드를 지원해요.

MlPredictModelStreamRequest 필드 (MlPredictModelStreamRequest fields)

MlPredictModelStreamRequest 메시지는 다음 필드를 받아요.

필드	Protobuf 타입	필수	설명
model_id	string	필수	예측을 실행할 모델의 ID예요. 모델은 지원되는 외부 호스팅 모델이어야 해요.
ml_predict_model_stream_request_body	MLPredictModelStreamRequestBody	필수	예측 파라미터를 담고 있는 요청 페이로드예요.

MLPredictModelStreamRequestBody 필드 (MLPredictModelStreamRequestBody fields)

MLPredictModelStreamRequestBody 메시지는 다음 필드를 받아요.

필드	Protobuf 타입	필수	설명
parameters	Parameters	필수	원격 모델에 전달되는 입력 파라미터예요.

Parameters 필드 (Parameters fields)

스트리밍 예측의 경우 Parameters 메시지는 다음 필드를 받아요. 모델 유형과 일치하는 필드를 제공하세요.

필드	Protobuf 타입	설명
messages	repeated Messages	OpenAI Chat Completion 같은 채팅 완성 모델에 보내는 대화 메시지예요.
inputs	string	모델에 보내는 입력 텍스트예요. 예를 들어 Amazon Bedrock Converse Stream 모델을 사용할 때예요.
x_llm_interface	string	모델 유형에 해당하는 LLM 인터페이스예요. 유효한 값은 `openai/v1/chat/completions`와 `bedrock/converse/claude`예요.

Messages 필드 (Messages fields)

Messages 메시지는 다음 필드를 받아요.

필드	Protobuf 타입	설명
role	string	메시지 발신자의 역할이에요. 예를 들어 `system` 또는 `user`.
content	string	메시지 콘텐츠예요.

응답 필드 (Response fields)

서버는 일련의 PredictResponse 메시지를 스트리밍해요. 각 메시지는 생성된 출력의 청크 하나를 담고 다음 필드를 제공해요.

필드	Protobuf 타입	설명
inference_results	repeated InferenceResults	청크에 대한 추론 결과예요.
inference_results.output	repeated Output	각 추론 결과에 대한 출력 객체예요.
inference_results.output.name	string	출력 필드의 이름(보통 `response`)이에요.
inference_results.output.data_as_map	DataAsMap	청크에 대한 응답 콘텐츠와 메타데이터예요.
inference_results.output.data_as_map.content	string	청크의 텍스트 콘텐츠예요. 전체 응답을 재구성하려면 청크들에 걸쳐 content 값을 이어붙여요.
inference_results.output.data_as_map.is_last	bool	이것이 스트림의 마지막 청크인지 여부예요. `true`이면 더 이상 메시지가 전송되지 않아요.

예제 요청 (Example request)

모델 입력을 담는 필드와 x_llm_interface 값은 모두 모델 유형에 따라 달라져요. 다음 예제들은 각 지원 모델 유형에 대한 gRPC 요청 메시지의 JSON 표현을 보여줘요. 두 예제 모두 model_id를 등록된 모델의 ID로 바꾸세요.

OpenAI Chat Completion 모델의 경우 messages 필드에 대화를 제공하고 x_llm_interface를 openai/v1/chat/completions로 설정해요.

{
  "model_id": "your_model_id",
  "ml_predict_model_stream_request_body": {
    "parameters": {
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful assistant."
        },
        {
          "role": "user",
          "content": "Can you summarize Prince Hamlet of William Shakespeare in around 100 words?"
        }
      ],
      "x_llm_interface": "openai/v1/chat/completions"
    }
  }
}

Amazon Bedrock Converse Stream 모델의 경우 inputs 필드에 입력 텍스트를 제공하고 x_llm_interface를 bedrock/converse/claude로 설정해요.

{
  "model_id": "your_model_id",
  "ml_predict_model_stream_request_body": {
    "parameters": {
      "inputs": "Can you summarize Prince Hamlet of William Shakespeare in around 100 words?",
      "x_llm_interface": "bedrock/converse/claude"
    }
  }
}

다음 예제는 OpenAI Chat Completion 모델에서 예측을 스트리밍하는 Java gRPC 클라이언트를 보여줘요. 모델 ID와 메시지를 모델 구성과 일치하는 값으로 바꾸세요.

import org.opensearch.protobufs.*;
import org.opensearch.protobufs.services.MLServiceGrpc;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

import java.util.Iterator;

public class PredictModelStreamClient {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 9400)
                .usePlaintext()
                .build();

        // Create a gRPC stub for ML operations
        MLServiceGrpc.MLServiceBlockingStub mlStub = MLServiceGrpc.newBlockingStub(channel);

        // Build the request parameters for an OpenAI Chat Completion model
        Parameters parameters = Parameters.newBuilder()
            .addMessages(Messages.newBuilder()
                .setRole("system")
                .setContent("You are a helpful assistant.")
                .build())
            .addMessages(Messages.newBuilder()
                .setRole("user")
                .setContent("Can you summarize Prince Hamlet of William Shakespeare in around 100 words?")
                .build())
            .setXLlmInterface("openai/v1/chat/completions")
            .build();

        // Create the streaming predict request
        MlPredictModelStreamRequest request = MlPredictModelStreamRequest.newBuilder()
            .setModelId("your_model_id")
            .setMlPredictModelStreamRequestBody(MLPredictModelStreamRequestBody.newBuilder()
                .setParameters(parameters)
                .build())
            .build();

        // Execute the request and read the streamed response
        try {
            Iterator<PredictResponse> responses = mlStub.predictModelStream(request);
            while (responses.hasNext()) {
                PredictResponse response = responses.next();
                for (InferenceResults results : response.getInferenceResultsList()) {
                    for (Output output : results.getOutputList()) {
                        DataAsMap chunk = output.getDataAsMap();
                        System.out.print(chunk.getContent());
                        if (chunk.getIsLast()) {
                            System.out.println("\n[stream complete]");
                        }
                    }
                }
            }
        } catch (io.grpc.StatusRuntimeException e) {
            System.err.println("gRPC predict stream request failed with status: " + e.getStatus());
            System.err.println("Error message: " + e.getMessage());
        }

        channel.shutdown();
    }
}

Amazon Bedrock Converse Stream 모델의 경우 addMessages 대신 setInputs를 사용해 요청 파라미터를 구성해요. 클라이언트 코드의 나머지는 동일해요.

Parameters parameters = Parameters.newBuilder()
    .setInputs("Can you summarize Prince Hamlet of William Shakespeare in around 100 words?")
    .setXLlmInterface("bedrock/converse/claude")
    .build();

MlPredictModelStreamRequest request = MlPredictModelStreamRequest.newBuilder()
    .setModelId("your_model_id")
    .setMlPredictModelStreamRequestBody(MLPredictModelStreamRequestBody.newBuilder()
        .setParameters(parameters)
        .build())
    .build();

예제 응답 (Example response)

서버는 일련의 PredictResponse 메시지를 반환해요. 각 메시지는 content 필드에 생성된 텍스트의 청크 하나를 담고, 마지막 메시지는 isLast를 true로 설정해요. 다음 예제는 스트리밍된 청크의 JSON 표현을 보여줘요.

{
  "inferenceResults": [
    {
      "output": [
        {
          "name": "response",
          "dataAsMap": {
            "content": "Hello",
            "isLast": false
          }
        }
      ]
    }
  ]
}

Predict Stream API — 스트리밍 예측의 REST 버전
Using gRPC APIs — gRPC 전송 구성과 클라이언트 요구 사항

더 알아보기 (Learn more)

OpenSearch 공식 문서

모델 스트림 예측 API