LLM 추론 API를 사용하면 웹 애플리케이션을 위해 대규모 언어 모델 (LLM)을 완전히 온디바이스로 실행할 수 있습니다. 이를 통해 텍스트 생성, 자연어 형식으로 정보 검색, 문서 요약 등 다양한 작업을 실행할 수 있습니다. 이 작업은 여러 텍스트-텍스트 대규모 언어 모델을 기본적으로 지원하므로 최신 온디바이스 생성형 AI 모델을 웹 앱에 적용할 수 있습니다. 최신 Gemma-3n 모델을 사용하는 경우 이미지 및 오디오 입력도 지원됩니다.
LLM 추론 API를 웹 애플리케이션에 빠르게 추가하려면 빠른 시작을 따르세요. LLM 추론 API를 실행하는 웹 애플리케이션의 기본 예는 샘플 애플리케이션을 참고하세요. LLM 추론 API의 작동 방식에 대한 자세한 내용은 구성 옵션, 모델 변환, LoRA 미세 조정 섹션을 참고하세요.
MediaPipe Studio 데모에서 이 작업을 직접 확인할 수 있습니다. 이 작업의 기능, 모델, 구성 옵션에 관한 자세한 내용은 개요를 참고하세요.
빠른 시작
다음 단계에 따라 LLM 추론 API를 웹 애플리케이션에 추가하세요. LLM 추론 API에는 WebGPU 호환 웹브라우저가 필요합니다. 호환되는 브라우저의 전체 목록은 GPU 브라우저 호환성을 참고하세요.
종속 항목 추가
LLM 추론 API는 @mediapipe/tasks-genai 패키지를 사용합니다.
로컬 스테이징에 필요한 패키지를 설치합니다.
npm install @mediapipe/tasks-genai
서버에 배포하려면 jsDelivr와 같은 콘텐츠 전송 네트워크 (CDN) 서비스를 사용하여 HTML 페이지에 코드를 직접 추가하세요.
<head>
<script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-genai/genai_bundle.cjs"
crossorigin="anonymous"></script>
</head>
모델 다운로드
HuggingFace에서 Gemma-3n E4B 또는 E2B를 다운로드합니다. 이름에 '-Web'이 포함된 모델은 웹 사용을 위해 특별히 변환되므로 이러한 모델 중 하나를 항상 사용하는 것이 좋습니다.
사용 가능한 모델에 관한 자세한 내용은 모델 문서를 참고하거나 HuggingFace 커뮤니티 페이지를 살펴보세요. 여기에는 문서에 포함되지 않았지만 웹용으로 특별히 변환된 270M, 4B, 12B, 27B, MedGemma-27B-Text와 같은 여러 추가 Gemma 3 변형이 제공됩니다.
프로젝트 디렉터리에 모델을 저장합니다.
<dev-project-root>/assets/gemma-3n-E4B-it-int4-Web.litertlm
baseOptions 객체 modelAssetPath 매개변수를 사용하여 모델의 경로를 지정합니다.
baseOptions: { modelAssetPath: `/assets/gemma-3n-E4B-it-int4-Web.litertlm`}
작업 초기화
기본 구성 옵션으로 작업을 초기화합니다.
const genai = await FilesetResolver.forGenAiTasks(
// path/to/wasm/root
"https://cdn.jsdelivr.net/npm/@mediapipe/tasks-genai@latest/wasm"
);
llmInference = await LlmInference.createFromOptions(genai, {
baseOptions: {
modelAssetPath: '/assets/gemma-3n-E4B-it-int4-Web.litertlm'
},
maxTokens: 1000,
topK: 40,
temperature: 0.8,
randomSeed: 101
});
태스크 실행
generateResponse() 함수를 사용하여 추론을 트리거합니다.
const response = await llmInference.generateResponse(inputPrompt);
document.getElementById('output').textContent = response;
대답을 스트리밍하려면 다음을 사용하세요.
llmInference.generateResponse(
inputPrompt,
(partialResult, done) => {
document.getElementById('output').textContent += partialResult;
});
멀티모달 프롬프트
Gemma-3n 모델의 경우 LLM 추론 API 웹 API가 멀티모달 프롬프트를 지원합니다. 멀티모달을 사용 설정하면 사용자가 프롬프트에 이미지, 오디오, 텍스트의 순서가 지정된 조합을 포함할 수 있습니다. 그러면 LLM이 텍스트 응답을 제공합니다.
시작하려면 MediaPipe 및 웹 호환 형식으로 Gemma-3n E4B 또는 Gemma-3n E2B를 사용하세요. 자세한 내용은 Gemma-3n 문서를 참고하세요.
비전 지원을 사용 설정하려면 maxNumImages가 양수 값으로 설정되어 있어야 합니다. 이는 LLM이 단일 프롬프트에서 처리할 수 있는 최대 이미지 조각 수를 결정합니다.
오디오 지원을 사용 설정하려면 supportAudio가 true로 설정되어 있는지 확인하세요.
llmInference = await LlmInference.createFromOptions(genai, {
baseOptions: {
modelAssetPath: '/assets/gemma-3n-E4B-it-int4-Web.litertlm'
},
maxTokens: 1000,
topK: 40,
temperature: 0.8,
randomSeed: 101,
maxNumImages: 5,
supportAudio: true,
});
이제 이전과 같이 응답을 생성할 수 있지만 문자열, 이미지, 오디오 데이터의 정렬된 배열을 사용합니다.
const response = await llmInference.generateResponse([
'<ctrl99>user\nDescribe ',
{imageSource: '/assets/test_image.png'},
' and then transcribe ',
{audioSource: '/assets/test_audio.wav'},
'<ctrl100>\n<ctrl99>model\n',
]);
비전의 경우 이미지 URL과 가장 일반적인 이미지, 동영상 또는 캔버스 객체가 지원됩니다. 오디오의 경우 단일 채널 AudioBuffer와 모노 채널 오디오 파일 URL만 지원됩니다. 소스 코드를 탐색하면 자세한 내용을 확인할 수 있습니다.
샘플 애플리케이션
샘플 애플리케이션은 LLM 추론 API를 사용하는 웹용 기본 텍스트 생성 앱의 예입니다. 이 앱을 자체 웹 앱의 시작점으로 사용하거나 기존 앱을 수정할 때 참조할 수 있습니다. 예시 코드는 GitHub에 호스팅되어 있습니다.
다음 명령어를 사용하여 Git 저장소를 클론합니다.
git clone https://github.com/google-ai-edge/mediapipe-samples
자세한 내용은 웹 설정 가이드를 참고하세요.
구성 옵션
다음 구성 옵션을 사용하여 웹 앱을 설정합니다.
| 옵션 이름 | 설명 | 값 범위 | 기본값 |
|---|---|---|---|
modelPath |
프로젝트 디렉터리 내에서 모델이 저장된 경로입니다. | 경로 | 해당 사항 없음 |
maxTokens |
모델이 처리하는 최대 토큰 수 (입력 토큰 + 출력 토큰)입니다. | 정수 | 512 |
topK |
모델이 생성의 각 단계에서 고려하는 토큰 수입니다. 예측을 확률이 가장 높은 상위 k개 토큰으로 제한합니다. | 정수 | 40 |
temperature |
생성 중에 도입된 무작위성의 양입니다. 온도가 높을수록 생성된 텍스트의 창의성이 높아지고 온도가 낮을수록 더 예측 가능한 생성이 이루어집니다. | 부동 소수점 수 | 0.8 |
randomSeed |
텍스트 생성 중에 사용된 무작위 시드입니다. | 정수 | 0 |
loraRanks |
런타임 중에 LoRA 모델에서 사용할 LoRA 순위입니다. 참고: GPU 모델과만 호환됩니다. | 정수 배열 | 해당 사항 없음 |
모델 변환
LLM 추론 API는 다음 유형의 모델과 호환되며, 일부 모델은 변환이 필요합니다. 표를 사용하여 모델에 필요한 단계 메서드를 확인합니다.
| 모델 | 전환 방법 | 호환되는 플랫폼 | 파일 형식 |
|---|---|---|---|
| Gemma-3 1B | 변환이 필요하지 않음 | Android, 웹 | .task |
| Gemma 2B, Gemma 7B, Gemma-2 2B | 변환이 필요하지 않음 | Android, iOS, 웹 | .bin |
| Phi-2, StableLM, Falcon | MediaPipe 변환 스크립트 | Android, iOS, 웹 | .bin |
| 모든 PyTorch LLM 모델 | AI Edge Torch 생성 라이브러리 | Android, iOS | .task |
다른 모델을 변환하는 방법을 알아보려면 모델 변환 섹션을 참고하세요.
LoRA 맞춤설정
LLM 추론 API는 PEFT (Parameter-Efficient Fine-Tuning) 라이브러리를 사용하여 LoRA (Low-Rank Adaptation) 튜닝을 지원합니다. LoRA 조정은 비용 효율적인 학습 프로세스를 통해 LLM의 동작을 맞춤설정하여 전체 모델을 재학습하는 대신 새로운 학습 데이터를 기반으로 학습 가능한 가중치 집합을 만듭니다.
LLM 추론 API는 Gemma-2 2B, Gemma 2B, Phi-2 모델의 어텐션 레이어에 LoRA 가중치를 추가하는 기능을 지원합니다. safetensors 형식으로 모델을 다운로드합니다.
LoRA 가중치를 만들려면 기본 모델이 safetensors 형식이어야 합니다. LoRA 학습 후 모델을 FlatBuffers 형식으로 변환하여 MediaPipe에서 실행할 수 있습니다.
LoRA 가중치 준비
PEFT의 LoRA 메서드 가이드를 사용하여 자체 데이터 세트에서 미세 조정된 LoRA 모델을 학습시킵니다.
LLM 추론 API는 어텐션 레이어의 LoRA만 지원하므로 LoraConfig에서 어텐션 레이어만 지정하세요.
# For Gemma
from peft import LoraConfig
config = LoraConfig(
r=LORA_RANK,
target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
)
# For Phi-2
config = LoraConfig(
r=LORA_RANK,
target_modules=["q_proj", "v_proj", "k_proj", "dense"],
)
준비된 데이터 세트에서 학습하고 모델을 저장하면 미세 조정된 LoRA 모델 가중치를 adapter_model.safetensors에서 사용할 수 있습니다. safetensors 파일은 모델 변환 중에 사용되는 LoRA 체크포인트입니다.
모델 변환
MediaPipe Python 패키지를 사용하여 모델 가중치를 Flatbuffer 형식으로 변환합니다. ConversionConfig는 기본 모델 옵션과 추가 LoRA 옵션을 지정합니다.
import mediapipe as mp
from mediapipe.tasks.python.genai import converter
config = converter.ConversionConfig(
# Other params related to base model
...
# Must use gpu backend for LoRA conversion
backend='gpu',
# LoRA related params
lora_ckpt=LORA_CKPT,
lora_rank=LORA_RANK,
lora_output_tflite_file=LORA_OUTPUT_FILE,
)
converter.convert_checkpoint(config)
변환기는 MediaPipe와 호환되는 두 개의 파일을 생성합니다. 하나는 기본 모델용이고 다른 하나는 LoRA 모델용입니다.
LoRA 모델 추론
웹은 런타임 중에 동적 LoRA를 지원합니다. 즉, 사용자가 초기화 중에 LoRA 순위를 선언합니다. 즉, 런타임 중에 다양한 LoRA 모델을 교체할 수 있습니다.
const genai = await FilesetResolver.forGenAiTasks(
// path/to/wasm/root
"https://cdn.jsdelivr.net/npm/@mediapipe/tasks-genai@latest/wasm"
);
const llmInference = await LlmInference.createFromOptions(genai, {
// options for the base model
...
// LoRA ranks to be used by the LoRA models during runtime
loraRanks: [4, 8, 16]
});
기본 모델을 초기화한 후 런타임 중에 LoRA 모델을 로드합니다. LLM 응답을 생성할 때 모델 참조를 전달하여 LoRA 모델을 트리거합니다.
// Load several LoRA models. The returned LoRA model reference is used to specify
// which LoRA model to be used for inference.
loraModelRank4 = await llmInference.loadLoraModel(loraModelRank4Url);
loraModelRank8 = await llmInference.loadLoraModel(loraModelRank8Url);
// Specify LoRA model to be used during inference
llmInference.generateResponse(
inputPrompt,
loraModelRank4,
(partialResult, done) => {
document.getElementById('output').textContent += partialResult;
});