블로그 | 모하지?

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

다중 모드 콘텐츠

멀티모달 콘텐츠란 텍스트, 이미지, 오디오, 비디오, 파일 등 다양한 유형의 콘텐츠를 말합니다. Koog를 사용하면 텍스트와 함께 user 메시지 내의 LLM에 이미지, 오디오, 비디오 및 파일을 보낼 수 있습니다. Kotlin의 해당 함수나 Java의 메서드를 사용하여 user 메시지에 이를 추가할 수 있습니다.

image(): 이미지(JPG, PNG, WebP, GIF)를 첨부합니다.
audio(): 오디오 파일(MP3, WAV, FLAC)을 첨부합니다.
video(): 비디오 파일(MP4, AVI, MOV)을 첨부합니다.
file() / binaryFile() / textFile(): 문서(PDF, TXT, MD 등)를 첨부합니다.

각 함수 또는 방법은 첨부 매개변수를 구성하는 두 가지 방법을 지원하므로 다음을 수행할 수 있습니다.

함수나 메소드에 URL이나 파일 경로를 전달하면 자동으로 첨부 매개변수를 처리합니다. file(), binaryFile() 및 textFile()의 경우 MIME 유형도 제공해야 합니다.
첨부 매개변수에 대한 사용자 정의 제어를 위해 ContentPart 개체를 생성하고 함수 또는 메서드에 전달합니다.

참고 다중 모드 콘텐츠 지원은 LLM provider에 따라 다릅니다. 지원되는 콘텐츠 유형에 대해서는 공급자 설명서를 확인하세요.

자동 구성된 첨부 파일

첨부 함수나 메소드에 URL이나 파일 경로를 전달하면 Koog는 자동으로 해당하는 파일 경로를 구성합니다. 파일 확장자를 기반으로 하는 첨부 파일 매개변수입니다.

텍스트 메시지와 자동 구성된 첨부 파일 목록을 포함하는 user 메시지의 일반적인 형식은 다음과 같습니다.

코틀린

1user {2    +"Describe these images:"34    image("https://example.com/test.png")5    image(Path("/path/to/image.png"))67    +"Focus on the main subjects."8}

자바

1ContentPartsBuilder partsBuilder = new ContentPartsBuilder();2partsBuilder.text("Describe these images:");3partsBuilder.image("https://example.com/test.png");4partsBuilder.text("Focus on the main subjects.");56Prompt prompt = Prompt.builder("image_analysis")7    .user(partsBuilder.build())8    .build();

Kotlin에서 + 연산자는 첨부 파일과 함께 사용자 메시지에 텍스트 콘텐츠를 추가합니다. Java에서는 ContentPartsBuilder의 text() 메서드를 사용합니다.

맞춤형으로 구성된 첨부 파일

ContentPart 인터페이스 각 첨부 파일에 대한 매개변수를 개별적으로 구성할 수 있습니다.

모든 첨부 파일은 ContentPart.Attachment 인터페이스를 구현합니다. 각 첨부 파일에 대한 특정 구현의 인스턴스를 생성하고 해당 매개변수를 구성한 다음 이를 전달할 수 있습니다. Kotlin의 해당 image(), audio(), video() 또는 file() 함수 또는 Java의 메서드.

텍스트 메시지와 사용자 정의 구성 첨부 파일 목록을 포함하는 user 메시지의 일반적인 형식은 다음과 같습니다.

코틀린

1user {2    +"Describe this image"3    image(4        ContentPart.Image(5            content = AttachmentContent.URL("https://example.com/capture.png"),6            format = "png",7            mimeType = "image/png",8            fileName = "capture.png"9        )10    )11}

자바

1Prompt prompt = Prompt.builder("custom_image")2    .user(List.of(3        new ContentPart.Text("Describe this image"),4        new ContentPart.Image(5            new AttachmentContent.URL("https://example.com/capture.png"),6            "png",7            "image/png",8            "capture.png"9        )10    ))11    .build();

Koog는 ContentPart.Attachment 인터페이스를 구현하는 각 미디어 유형에 대해 다음과 같은 특수 클래스를 제공합니다.

ContentPart.Image: JPG 또는 PNG 파일과 같은 이미지 첨부 파일.
ContentPart.Audio: MP3 또는 WAV 파일과 같은 오디오 첨부 파일.
ContentPart.Video: MP4 또는 AVI 파일과 같은 비디오 첨부 파일.
ContentPart.File: PDF 또는 TXT 파일과 같은 첨부 파일.

모든 ContentPart.Attachment 유형은 다음 매개변수를 허용합니다.

이름	데이터 유형	필수의	설명
`content`	AttachmentContent	예	제공된 파일 콘텐츠의 소스입니다.
`format`	끈	예	제공된 파일의 형식입니다. 예를 들어 `png`입니다.
`mimeType`	끈	`ContentPart.File`에만 해당	제공된 파일의 MIME 유형입니다. `ContentPart.Image`, `ContentPart.Audio` 및 `ContentPart.Video`의 경우 기본값은 `<type>/<format>`입니다(예: `image/png`). `ContentPart.File`의 경우 명시적으로 제공해야 합니다.
`fileName`	끈?	아니요	확장자를 포함한 제공된 파일의 이름입니다. 예를 들어 `screenshot.png`입니다.

첨부파일 내용

AttachmentContent 인터페이스의 구현은 LLM에 입력으로 제공되는 콘텐츠의 유형과 소스를 정의합니다.

AttachmentContent.URL은 제공된 콘텐츠의 URL을 정의합니다.

1AttachmentContent.URL("https://example.com/image.png")

AttachmentContent.Binary.Bytes은 파일 내용을 바이트 배열로 정의합니다.

1AttachmentContent.Binary.Bytes(byteArrayOf(/* ... */))

AttachmentContent.Binary.Base64은 파일 콘텐츠를 파일 데이터가 포함된 Base64 인코딩 문자열로 정의합니다.

1AttachmentContent.Binary.Base64("iVBORw0KGgoAAAANS...")

AttachmentContent.PlainText은 파일 콘텐츠를 일반 텍스트로 정의합니다(ContentPart.File에만 해당).

1AttachmentContent.PlainText("This is the file content.")

혼합 첨부 파일

별도의 프롬프트나 메시지에 다양한 유형의 첨부 파일을 제공하는 것 외에도 단일 user() 메시지에 다양한 유형의 첨부 파일을 제공할 수도 있습니다.

코틀린

1val prompt = prompt("mixed_content") {2    system("You are a helpful assistant.")34    user {5        +"Compare the image with the document content."6        image(Path("/path/to/image.png"))7        binaryFile(Path("/path/to/page.pdf"), "application/pdf")8        +"Structure the result as a table"9    }10}

자바

1Prompt prompt = Prompt.builder("mixed_content_example")2.system("You are a helpful assistant.")3.user(List.of(4    new ContentPart.Text("Please analyze this image and the attached document."),5    new ContentPart.Image(6        new AttachmentContent.URL("https://example.com/image.png"),7        "png",8        "image/png",9        "image.png"10    ),11    new ContentPart.File(12        new AttachmentContent.URL("https://example.com/document.pdf"),13        "pdf",14        "application/pdf",15        "document.pdf"16    ),17    new ContentPart.Text("Summarize the differences.")18))19.build();

다음 단계

단일 LLM 제공업체와 협력하는 경우 LLM clients으로 프롬프트를 실행하세요.
여러 LLM 제공업체와 협력하는 경우 prompt executors으로 프롬프트를 실행하세요.