LM Studio 이미지 첨부 파일 작동 방식 분석 및 프로그래밍 방식 주입 스키마 공유

커뮤니티 반응

작성자가 9번의 시도 끝에 찾아낸 구체적인 스키마와 해결책에 대해 긍정적인 반응이 이어졌으며, 특히 자동화 워크플로우를 구축하려는 사용자들에게 유용한 정보로 평가받았다.

실용적 조언

이미지 주입 자동화 시 Python 스크립트를 사용하여 JSON을 생성하고 줄바꿈 오염을 방지하라.
메타데이터의 preview.data 필드에 반드시 'data:image/png;base64,' 접두사를 포함시켜라.
파일 식별자의 공백-대시-공백 패턴(' - ')을 엄격히 준수하라.

섹션별 상세

LM Studio의 저장 구조는 대화 기록이 담긴 'conversations' 디렉토리와 첨부 파일 바이너리가 담긴 'user-files' 디렉토리로 엄격히 분리되어 관리된다. 이미지가 정상적으로 렌더링되려면 이미지 바이너리, 메타데이터 JSON 사이드카, 그리고 이들을 참조하는 대화 JSON이라는 세 가지 요소가 상호 일관성을 유지하며 존재해야 함이 확인됐다.

스크립트를 통해 생성된 이미지가 포함된 LM Studio 대화 화면 스크린샷 — Screenshot사용자가 직접 GUI를 통해 이미지를 업로드하지 않고, Python 스크립트로 생성한 대화 파일과 이미지 메타데이터가 LM Studio 내에서 정상적으로 렌더링됨을 증명한다. 대화 내용에서 AI 어시스턴트가 'Python 스크립트가 이 대화 전체를 작성했다'고 언급하며 기술적 성공을 확인해준다.

메타데이터 스키마 분석 결과, 'type' 필드는 'image/png'와 같은 MIME 타입이 아닌 단순 'image' 문자열이어야 한다. 특히 'preview.data' 필드에는 반드시 22자의 데이터 URI 접두사('data:image/png;base64,')가 포함된 전체 Base64 문자열이 들어가야 하며, 접두사가 없으면 렌더링이 실패한다.

json

{
  "type": "image",
  "sizeBytes": 2415214,
  "originalName": "yourfile.png",
  "fileIdentifier": "1772813131243 - 456.png",
  "preview": {
    "data": "data:image/png;base64,iVBORw0KGgo..."
  },
  "sha256Hex": "da915ab154..."
}

LM Studio에서 이미지 첨부 파일을 인식하기 위해 필요한 메타데이터 JSON 스키마

파일 식별자인 'fileIdentifier'는 '에포크 밀리초 - 3자리 랜덤숫자.png' 형식을 정확히 따라야 하며, 파일 시스템상의 실제 파일명과 일치해야 한다. 또한 SHA256 해시값과 파일 크기 정보가 실제 바이너리와 일치하지 않으면 LM Studio 내부 엔진에서 해당 파일을 유효하지 않은 것으로 간주한다.

Python의 'json.dump()'를 사용하여 파일을 생성하는 것이 권장된다. 쉘의 heredoc 등을 사용하면 Base64 문자열 끝에 의도치 않은 줄바꿈이 삽입되어 메타데이터 파일이 손상될 위험이 크기 때문이다. LM Studio는 파일 시스템을 실시간으로 감시하므로 별도의 재시작 없이도 새로 생성된 대화와 이미지를 즉시 인식한다.

용어 해설

데이터 URI(Data URI): — 이미지나 문서 같은 데이터를 별도의 외부 파일 링크 대신 텍스트 문자열 형태로 직접 문서 안에 포함하는 방식이다. 'data:image/png;base64,...'와 같은 형식을 사용하며, 웹 브라우저나 앱이 별도의 네트워크 요청 없이 즉시 데이터를 렌더링할 수 있게 한다.
사이드카 파일(Sidecar File): — 주 데이터 파일과 함께 존재하며 해당 파일의 메타데이터나 설정 정보를 담고 있는 별도의 보조 파일이다. LM Studio에서는 이미지 바이너리 파일 외에 해당 이미지의 원본 이름, 해시값, 미리보기 데이터를 담은 JSON 파일을 사이드카 형태로 관리한다.
베이스64(Base64): — 8비트 이진 데이터를 64진법의 텍스트로 인코딩하는 방식이다. 바이너리 데이터를 텍스트 기반의 프로토콜이나 JSON 파일 내에 안전하게 포함시키기 위해 필수적으로 사용되며, 인코딩 시 원본보다 크기가 약 33% 증가한다.
SHA-256: — 데이터의 무결성을 검증하기 위해 사용되는 256비트 길이의 암호화 해시 함수이다. 파일의 내용이 조금이라도 바뀌면 해시값이 완전히 달라지므로, LM Studio는 이 값을 통해 첨부된 이미지가 변조되지 않았는지 확인한다.

언급된 도구

LM Studio추천

로컬 LLM 추론 및 대화 인터페이스

언급된 리소스

GitHubLM Studio Image Injection Gist