목록으로
기술

프롬프트 실행자

·3분 읽기
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM

원문: Koog Documentation — prompts/prompt-executors.md 이 글은 Koog 공식 문서의 prompts/prompt-executors.md 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

프롬프트 실행자

프롬프트 실행기는 하나 이상의 LLM 클라이언트의 수명주기를 관리할 수 있는 더 높은 수준의 추상화를 제공합니다. 통합 인터페이스를 통해 여러 LLM 제공업체와 협력하여 제공업체별 세부 정보를 추상화하고, 이들과 폴백 간의 동적 전환이 가능합니다.

실행자 유형

Koog는 PromptExecutor 인터페이스를 구현하는 세 가지 주요 유형의 프롬프트 실행기를 제공합니다.

유형 클래스 설명
단일 공급자 SingleLLMPromptExecutor 하나의 공급자에 대해 단일 LLM 클라이언트를 래핑합니다. 에이전트가 단일 LLM 제공자 내의 모델 간 전환만 필요한 경우 이 실행기를 사용하십시오.
다중 공급자 MultiLLMPromptExecutor 여러 LLM 클라이언트를 래핑하고 LLM 공급자를 기반으로 호출을 라우팅합니다. 요청한 클라이언트를 사용할 수 없는 경우 구성된 대체 공급자와 LLM을 선택적으로 사용할 수 있습니다. 에이전트가 다른 공급자의 LLM 간에 전환해야 하는 경우 이 실행기를 사용하십시오.
라우팅 RoutingLLMPromptExecutor 라우팅 전략을 사용하여 여러 클라이언트 인스턴스에 걸쳐 지정된 LLM 모델에 대한 요청을 배포합니다. 이 실행기를 사용하면 속도 제한을 피하고 처리량을 향상시키며 로드 밸런싱을 통해 장애 조치 전략을 구현할 수 있습니다.

단일 제공자 실행자 만들기

특정 LLM 제공업체에 대한 프롬프트 실행자를 생성하려면 다음을 수행하십시오.

  1. 해당 API 키를 사용하여 특정 공급자에 대한 LLM 클라이언트를 구성합니다.
  2. MultiLLMPromptExecutor을 사용하여 프롬프트 실행기를 만듭니다.

예는 다음과 같습니다.

코틀린

1val openAIClient = OpenAILLMClient(System.getenv("OPENAI_API_KEY"))2val promptExecutor = MultiLLMPromptExecutor(openAIClient)

자바

1OpenAILLMClient openAIClient = new OpenAILLMClient(System.getenv("OPENAI_API_KEY"));2MultiLLMPromptExecutor promptExecutor = new MultiLLMPromptExecutor(openAIClient);

다중 제공자 실행자 만들기

여러 LLM 제공업체와 작동하는 프롬프트 실행기를 생성하려면 다음을 수행하세요.

  1. 해당 API 키를 사용하여 필수 LLM 공급자에 대한 클라이언트를 구성합니다.
  2. 구성된 클라이언트를 MultiLLMPromptExecutor 클래스 생성자에 전달하여 프롬프트 실행기를 만듭니다. 여러 LLM 제공업체와 함께.

코틀린

1val openAIClient = OpenAILLMClient(System.getenv("OPENAI_API_KEY"))2val ollamaClient = OllamaClient()34val multiExecutor = MultiLLMPromptExecutor(5    LLMProvider.OpenAI to openAIClient,6    LLMProvider.Ollama to ollamaClient7)

자바

1OpenAILLMClient openAIClient = new OpenAILLMClient(System.getenv("OPENAI_API_KEY"));2OllamaClient ollamaClient = new OllamaClient();34MultiLLMPromptExecutor promptExecutor = new MultiLLMPromptExecutor(openAIClient, ollamaClient);

라우팅 실행기 만들기

참고: Experimental API 라우팅 기능은 실험적이며 향후 릴리스에서 변경될 수 있습니다. 이를 사용하려면 @OptIn(ExperimentalRoutingApi::class)을 선택하세요.

라우팅 전략을 사용하여 여러 LLM 클라이언트 인스턴스에 요청을 분산하는 프롬프트 실행기를 생성하려면 다음을 수행합니다.

  1. 해당 API 키를 사용하여 여러 클라이언트 인스턴스(동일하거나 다른 LLM 공급자용일 수 있음)를 구성합니다.
  2. RoundRobinRouter과 같은 라우팅 전략을 사용하여 라우터를 만듭니다.
  3. 라우터를 RoutingLLMPromptExecutor 클래스 생성자에 전달합니다.

이는 속도 제한을 피하고, 처리량을 개선하고, 장애 조치 전략을 구현하는 데 유용합니다.

코틀린

1// Create multiple client instances2val openAI1 = OpenAILLMClient(apiKey = "openai-key-1")3val openAI2 = OpenAILLMClient(apiKey = "openai-key-2")4val anthropic = AnthropicLLMClient(apiKey = "anthropic-key")56// Create router with round-robin strategy7val router = RoundRobinRouter(openAI1, openAI2, anthropic)89// Create routing executor10val routingExecutor = RoutingLLMPromptExecutor(router)

자바

1// Create multiple client instances2OpenAILLMClient openAI1 = new OpenAILLMClient("openai-key-1");3OpenAILLMClient openAI2 = new OpenAILLMClient("openai-key-2");4AnthropicLLMClient anthropic = new AnthropicLLMClient("anthropic-key");56// Create router with round-robin strategy7RoundRobinRouter router = new RoundRobinRouter(openAI1, openAI2, anthropic);89// Create routing executor10RoutingLLMPromptExecutor routingExecutor = new RoutingLLMPromptExecutor(router);

이 실행기로 프롬프트를 실행하면 OpenAI 모델에 대한 요청은 라운드 로빈 전략을 사용하여 openAI1과 openAI2 간에 번갈아 가며 수행됩니다. 라운드 로빈은 공급자별로 독립적인 카운터를 유지하므로 Anthropic 모델에 대한 요청은 항상 단일 anthropic 클라이언트로 이동합니다.

LLMClientRouter 인터페이스를 구현하는 클래스를 생성하여 사용자 정의 라우팅 전략을 구현할 수도 있습니다.

사전 정의된 프롬프트 실행자

더 빠른 설정을 위해 Koog는 Kotlin과 Java 모두에서 공통 공급자에 대해 즉시 사용 가능한 실행기 구현을 제공합니다.

다음 표에는 사전 정의된 단일 공급자 실행자가 포함되어 있습니다. 특정 LLM 클라이언트로 구성된 SingleLLMPromptExecutor을 반환합니다.

LLM 제공업체 프롬프트 집행자 설명
오픈AI simpleOpenAIExecutor OpenAI 모델로 프롬프트를 실행하는 OpenAILLMClient을 래핑합니다.
오픈AI simpleAzureOpenAIExecutor Azure OpenAI 서비스를 사용하도록 구성된 OpenAILLMClient을 래핑합니다.
인류학 simpleAnthropicExecutor 인류 모델로 프롬프트를 실행하는 AnthropicLLMClient을 래핑합니다.
Google simpleGoogleAIExecutor Google 모델로 프롬프트를 실행하는 GoogleLLMClient을 래핑합니다.
오픈라우터 simpleOpenRouterExecutor OpenRouter로 프롬프트를 실행하는 OpenRouterLLMClient을 래핑합니다.
아마존 기반암 simpleBedrockExecutor AWS Bedrock으로 프롬프트를 실행하는 BedrockLLMClient을 래핑합니다.
아마존 기반암 simpleBedrockExecutorWithBearerToken BedrockLLMClient을 래핑하고 제공된 Bedrock API 키를 사용하여 요청을 보냅니다.
미스트랄 simpleMistralAIExecutor Mistral 모델로 프롬프트를 실행하는 MistralAILLMClient을 래핑합니다.
올라마 simpleOllamaAIExecutor Ollama로 프롬프트를 실행하는 OllamaClient를 래핑합니다.

다음은 사전 정의된 실행기를 생성하는 예입니다.

코틀린

1// Create an OpenAI executor2val promptExecutor = simpleOpenAIExecutor("OPENAI_API_KEY")

자바

1// Create an OpenAI executor2PromptExecutor openAIExecutor = simpleOpenAIExecutor("OPENAI_API_KEY");

프롬프트 실행

프롬프트 실행기를 사용하여 프롬프트를 실행하려면 다음을 수행합니다.

  1. 프롬프트 실행자를 만듭니다.
  2. execute() 방법을 사용하여 특정 LLM으로 프롬프트를 실행합니다.

예는 다음과 같습니다.

코틀린

1// Create an OpenAI executor2val promptExecutor = simpleOpenAIExecutor("OPENAI_API_KEY")34// Execute a prompt5val response = promptExecutor.execute(6    prompt = prompt("demo") { user("Summarize this.") },7    model = OpenAIModels.Chat.GPT4o8)

자바

1// Create an OpenAI executor2PromptExecutor promptExecutor = simpleOpenAIExecutor("OPENAI_API_KEY");34// Create a prompt5Prompt prompt = Prompt.builder("demo")6    .user("Summarize this.")7    .build();89// Run the prompt10List<Message.Response> response = promptExecutor.execute(prompt, OpenAIModels.Chat.GPT4o);

그러면 GPT4o 모델을 사용하여 프롬프트가 실행되고 응답이 반환됩니다.

참고 프롬프트 실행자는 다양한 기능을 사용하여 프롬프트를 실행하는 방법을 제공합니다. 스트리밍, 객관식 생성, 콘텐츠 조정 등이 있습니다. 프롬프트 실행기는 LLM 클라이언트를 래핑하므로 각 실행기는 해당 클라이언트의 기능을 지원합니다. 자세한 내용은 LLM clients을 참조하세요.

공급자 간 전환

MultiLLMPromptExecutor을 사용하여 여러 LLM 제공업체와 협력할 때 이들 제공업체 간에 전환할 수 있습니다. 프로세스는 다음과 같습니다.

  1. 사용하려는 각 공급자에 대해 LLM 클라이언트 인스턴스를 만듭니다.
  2. LLM 공급자를 LLM 클라이언트에 매핑하는 MultiLLMPromptExecutor을 만듭니다.
  3. execute() 메서드에 인수로 전달된 해당 클라이언트의 모델을 사용하여 프롬프트를 실행합니다. 프롬프트 실행자는 모델 공급자를 기반으로 해당 클라이언트를 사용하여 프롬프트를 실행합니다.

다음은 공급자 간 전환의 예입니다.

코틀린

1// Create LLM clients for OpenAI, Anthropic, and Google providers2val openAIClient = OpenAILLMClient("OPENAI_API_KEY")3val anthropicClient = AnthropicLLMClient("ANTHROPIC_API_KEY")4val googleClient = GoogleLLMClient("GOOGLE_API_KEY")56// Create a MultiLLMPromptExecutor that maps LLM providers to LLM clients7val executor = MultiLLMPromptExecutor(8    LLMProvider.OpenAI to openAIClient,9    LLMProvider.Anthropic to anthropicClient,10    LLMProvider.Google to googleClient11)1213// Create a prompt14val p = prompt("demo") { user("Summarize this.") }1516// Run the prompt with an OpenAI model; the prompt executor automatically switches to the OpenAI client17val openAIResult = executor.execute(p, OpenAIModels.Chat.GPT4o)1819// Run the prompt with an Anthropic model; the prompt executor automatically switches to the Anthropic client20val anthropicResult = executor.execute(p, AnthropicModels.Sonnet_4_5)

자바

1// Create LLM clients for OpenAI, Anthropic, and Google providers2OpenAILLMClient openAIClient = new OpenAILLMClient("OPENAI_API_KEY");3AnthropicLLMClient anthropicClient = new AnthropicLLMClient("ANTHROPIC_API_KEY");4GoogleLLMClient googleClient = new GoogleLLMClient("GOOGLE_API_KEY");56// Create a MultiLLMPromptExecutor that maps LLM providers to LLM clients7MultiLLMPromptExecutor promptExecutor = new MultiLLMPromptExecutor(8    Map.of(9        LLMProvider.OpenAI, openAIClient,10        LLMProvider.Anthropic, anthropicClient,11        LLMProvider.Google, googleClient12    )13);1415// Create a prompt16Prompt prompt = Prompt.builder("demo")17    .user("Summarize this.")18    .build();1920// Run the prompt with an OpenAI model; the prompt executor automatically switches to the OpenAI client21List<Message.Response> openAIResult = promptExecutor.execute(prompt, OpenAIModels.Chat.GPT4o);2223// Run the prompt with an Anthropic model; the prompt executor automatically switches to the Anthropic client24List<Message.Response> anthropicResult = promptExecutor.execute(prompt, AnthropicModels.Sonnet_4_5);

요청한 클라이언트를 사용할 수 없을 때 사용할 대체 LLM 공급자 및 모델을 선택적으로 구성할 수 있습니다. 자세한 내용은 Configuring fallbacks을 참조하세요.

대체 구성

요청된 LLM 클라이언트를 사용할 수 없을 때 대체 LLM 공급자 및 모델을 사용하도록 다중 공급자 및 라우팅 프롬프트 실행기를 구성할 수 있습니다.

대체 메커니즘을 구성하려면 MultiLLMPromptExecutor 또는 RoutingLLMPromptExecutor을 생성할 때 대체 설정을 전달하세요.

코틀린

1val openAIClient = OpenAILLMClient(System.getenv("OPENAI_API_KEY"))2val ollamaClient = OllamaClient()34val multiExecutor = MultiLLMPromptExecutor(5    LLMProvider.OpenAI to openAIClient,6    LLMProvider.Ollama to ollamaClient,7    fallback = MultiLLMPromptExecutor.FallbackPromptExecutorSettings(8        fallbackProvider = LLMProvider.Ollama,9        fallbackModel = OllamaModels.Meta.LLAMA_3_210    )11)

자바

1OpenAILLMClient openAIClient = new OpenAILLMClient(System.getenv("OPENAI_API_KEY"));2OllamaClient ollamaClient = new OllamaClient();34MultiLLMPromptExecutor multiExecutor = new MultiLLMPromptExecutor(5    Map.of(6        LLMProvider.OpenAI, openAIClient,7        LLMProvider.Ollama, ollamaClient8    ),9    new MultiLLMPromptExecutor.FallbackPromptExecutorSettings(10        LLMProvider.Ollama,11        OllamaModels.Meta.LLAMA_3_212    )13);

MultiLLMPromptExecutor에 포함되지 않은 LLM 제공업체의 모델을 전달하는 경우, 프롬프트 실행자는 대체 모델을 사용합니다.

코틀린

1// Create a prompt2val p = prompt("demo") { user("Summarize this") }3// If you pass a Google model, the prompt executor will use the fallback model, as the Google client is not included4val response = multiExecutor.execute(p, GoogleModels.Gemini2_5Pro)

자바

1// Create a prompt2Prompt p = Prompt.builder("demo")3    .user("Summarize this")4    .build();56// If you pass a Google model, the prompt executor will use the fallback model, as the Google client is not included7List<Message.Response> response = multiExecutor.execute(p, GoogleModels.Gemini2_5Pro);

참고 대체는 execute() 및 executeMultipleChoices() 방법에만 사용할 수 있습니다.

#Koog#JetBrains#AI Agent#Kotlin#Java#JVM