Ollama
Ollama 어댑터는 Ollama를 통해 실행되는 로컬 모델에 액세스할 수 있도록 하며, 완전한 개인정보 보호와 API 비용 없이 자체 인프라에서 AI 모델을 실행할 수 있게 합니다.
설치
npm install @tanstack/ai-ollama
기본 사용법
import { chat } from "@tanstack/ai";
import { ollamaText } from "@tanstack/ai-ollama";
const stream = chat({
adapter: ollamaText("llama3"),
messages: [{ role: "user", content: "Hello!" }],
});
기본 사용법 - 사용자 지정 호스트
import { chat } from "@tanstack/ai";
import { createOllamaChat } from "@tanstack/ai-ollama";
const adapter = createOllamaChat("llama3", "http://your-server:11434");
const stream = chat({
adapter,
messages: [{ role: "user", content: "Hello!" }],
});
구성
import { createOllamaChat } from "@tanstack/ai-ollama";
// Custom host (URL string)
const adapter = createOllamaChat("llama3", "http://your-server:11434");
// Custom client config (e.g., custom headers, fetch)
const adapter2 = createOllamaChat("llama3", {
host: "http://your-server:11434",
headers: { Authorization: "Bearer ..." },
});
사용 가능한 모델
Ollama 인스턴스에서 사용 가능한 모델을 확인하려면 다음을 실행합니다.
ollama list
인기 모델
llama3/llama3.1/llama3.2- Meta 의 Llama 모델mistral/mistral:7b- Mistral AI 모델mixtral- Mixtral MoE 모델codellama- 코드를 위한 Llamaphi3- Microsoft 의 Phi 모델gemma/gemma2- Google 의 Gemma 모델qwen2/qwen2.5- Alibaba 의 Qwen 모델deepseek-coder- DeepSeek 코딩 모델
예시: 채팅 완료
import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { ollamaText } from "@tanstack/ai-ollama";
export async function POST(request: Request) {
const { messages } = await request.json();
const stream = chat({
adapter: ollamaText("llama3"),
messages,
});
return toServerSentEventsResponse(stream);
}
예시: 도구 사용
import { chat, toServerSentEventsResponse, toolDefinition } from "@tanstack/ai";
import { ollamaText } from "@tanstack/ai-ollama";
import { z } from "zod";
const getLocalDataDef = toolDefinition({
name: "get_local_data",
description: "Get data from local storage",
inputSchema: z.object({
key: z.string(),
}),
});
const getLocalData = getLocalDataDef.server(async ({ key }) => {
// Access local data
return { data: "..." };
});
export async function POST(request: Request) {
const { messages } = await request.json();
const stream = chat({
adapter: ollamaText("llama3"),
messages,
tools: [getLocalData],
});
return toServerSentEventsResponse(stream);
}
참고: 도구 지원은 모델에 따라 다릅니다. llama3, mistral, qwen2와 같은 모델은 일반적으로 도구 호출을 잘 지원합니다.
모델 옵션
Ollama는 다양한 공급자별 옵션을 지원합니다. 다른 공급자와 달리 Ollama는 샘플링 및 러너 매개변수를 modelOptions 내부의 options 객체 안에 중첩합니다. temperature, top_p, num_predict(토큰 제한 키)는 모두 modelOptions.options 아래에 있습니다.
import { chat } from "@tanstack/ai";
import { ollamaText } from "@tanstack/ai-ollama";
const stream = chat({
adapter: ollamaText("llama3:latest"),
messages: [{ role: "user", content: "Hello!" }],
modelOptions: {
options: {
temperature: 0.7,
top_p: 0.9,
top_k: 40,
num_predict: 1000, // Max tokens to generate
repeat_penalty: 1.1,
num_ctx: 4096, // Context window size
num_gpu: -1, // GPU layers (-1 = auto)
},
},
});
이전에
chat()의 루트에서temperature/topP/maxTokens를 전달했다면 Ollama에서는 각각modelOptions.options.temperature,modelOptions.options.top_p,modelOptions.options.num_predict에 매핑된다는 점에 유의합니다. Sampling Options를 modelOptions로 이동을 참조하세요.
고급 옵션
모든 샘플링 및 러너 매개변수는 modelOptions.options 아래에 중첩됩니다.
modelOptions: {
options: {
// Sampling
temperature: 0.7,
top_p: 0.9,
top_k: 40,
min_p: 0.05,
typical_p: 1.0,
// Generation
num_predict: 1000,
repeat_penalty: 1.1,
repeat_last_n: 64,
penalize_newline: false,
// Performance
num_ctx: 4096,
num_batch: 512,
num_gpu: -1,
num_thread: 0, // 0 = auto
// Memory
use_mmap: true,
use_mlock: false,
// Mirostat sampling
mirostat: 0, // 0 = disabled, 1 = Mirostat, 2 = Mirostat 2.0
mirostat_tau: 5.0,
mirostat_eta: 0.1,
},
}
요약
긴 텍스트 콘텐츠를 로컬에서 요약합니다.
import { summarize } from "@tanstack/ai";
import { ollamaSummarize } from "@tanstack/ai-ollama";
const result = await summarize({
adapter: ollamaSummarize("llama3"),
text: "Your long text to summarize...",
maxLength: 100,
style: "concise", // "concise" | "bullet-points" | "paragraph"
});
console.log(result.summary);
임베딩
모든 Ollama 임베딩 모델을 사용하여 로컬에서 임베딩 벡터를 생성합니다.
import { embed } from "@tanstack/ai";
import { ollamaEmbedding } from "@tanstack/ai-ollama";
const result = await embed({
adapter: ollamaEmbedding("nomic-embed-text"),
input: ["a red guitar", "a blue drum kit"],
});
console.log(result.embeddings[0]?.vector);
알려진 모델(nomic-embed-text, mxbai-embed-large, all-minilm, snowflake-arctic-embed, bge-m3, embeddinggemma)은 자동 완성을 지원하며, 다른 모델 이름도 허용됩니다. 먼저 ollama pull nomic-embed-text로 모델을 가져옵니다. 출력 차원은 모델마다 고정되므로 최상위 dimensions 옵션은 지원되지 않습니다.
전체 API는 임베딩 가이드를 참조하세요.
Ollama 설정
1. Ollama 설치
# macOS
brew install ollama
# Linux
curl -fsSL https://ollama.com/install.sh | sh
# Windows
# Download from https://ollama.com
2. 모델 가져오기
ollama pull llama3
3. Ollama 서버 시작
ollama serve
서버는 기본적으로 http://localhost:11434에서 실행됩니다.
원격 서버에서 실행
import { createOllamaChat } from "@tanstack/ai-ollama";
const adapter = createOllamaChat("llama3", "http://your-server:11434");
네트워크 인터페이스에서 Ollama를 노출하려면 다음을 실행합니다.
OLLAMA_HOST=0.0.0.0:11434 ollama serve
환경 변수
선택적으로 환경 변수에서 호스트를 설정합니다.
OLLAMA_HOST=http://localhost:11434
API 참조
ollamaText(model)
환경의 OLLAMA_HOST를 사용하여 Ollama 텍스트/채팅 어댑터를 생성합니다(기본값은 http://localhost:11434).
매개변수:
model- 모델 이름(예:"llama3","mistral:7b")
createOllamaChat(model, hostOrConfig?)
명시적인 호스트 또는 클라이언트 구성으로 Ollama 텍스트/채팅 어댑터를 생성합니다.
Parameters:
model- 모델 이름hostOrConfig?-OLLAMA_HOST형식의 URL 문자열 또는OllamaClientConfig객체(예:{ host, headers, fetch })
ollamaSummarize(model) / createOllamaSummarize(model, hostOrConfig?)
Ollama 요약 어댑터를 생성하며, 채팅 어댑터와 동일한 시그니처 형태를 사용합니다.
Ollama의 장점
- ✅ 개인정보 보호 - 데이터가 자체 인프라에 남습니다.
- ✅ 비용 - 하드웨어 비용 외 API 비용이 없습니다.
- ✅ 사용자 지정 - 호환되는 모든 모델을 사용할 수 있습니다.
- ✅ 오프라인 - 인터넷 없이 작동합니다.
- ✅ 속도 - 로컬 배포에서는 네트워크 지연이 없습니다.
제한 사항
- 이미지 생성: Ollama는 이미지 생성을 지원하지 않습니다. 이미지 생성에는 OpenAI 또는 Gemini를 사용합니다.
- 성능: 하드웨어에 따라 달라집니다(대형 모델에는 GPU를 권장합니다).