LlamaIndex.TS 설치하기

프로젝트에 LlamaIndex.TS를 설치하고 세팅하는 방법을 정리해볼게요. TypeScript 프로젝트라면 패키지 몇 개 설치하고 환경 변수만 잡아주면 바로 시작할 수 있어요.

출처: 공식문서

빠른 시작

핵심 패키지를 설치해요.

npm i llamaindex

대부분의 경우 LLM 프로바이더와 Workflow 패키지도 함께 필요해요.

npm i @llamaindex/openai @llamaindex/workflow

환경 설정

API 키

대부분의 LLM 프로바이더는 API 키를 요구해요. OpenAI 키(또는 다른 프로바이더)를 설정하세요.

export OPENAI_API_KEY=your-api-key

또는 .env 파일을 써도 돼요.

echo "OPENAI_API_KEY=your-api-key" > .env

⚠️ API 키를 저장소에 커밋하면 안 돼요.

환경 변수 불러오기

Node.js 애플리케이션이라면:

node --env-file .env your-script.js

다른 환경에서는 아래의 배포별 가이드를 참고하면 됩니다.

TypeScript 설정

LlamaIndex.TS는 TypeScript로 만들어져 있어 타입 안전성이 뛰어나요. tsconfig.json에 다음 설정을 추가하세요.

{
  "compilerOptions": {
    // Essential for module resolution
    "moduleResolution": "bundler", // or "nodenext" | "node16" | "node"

    // Required for Web Stream API support
    "lib": ["DOM.AsyncIterable"],

    // Recommended for better compatibility
    "target": "es2020",
    "module": "esnext"
  }
}

첫 에이전트 실행하기

셋업

아직 프로젝트가 없다면 새 폴더에서 새 프로젝트를 만들 수 있어요.

npm init
npm i -D typescript @types/node
npm i @llamaindex/openai @llamaindex/workflow llamaindex zod

에이전트 실행

example.ts 파일을 만드세요. 이 코드는:

에이전트가 사용할 두 개의 도구를 만들어요.
- 두 숫자를 더하는 sumNumbers 도구
- 숫자를 나누는 divideNumbers 도구
생성하고 싶은 데이터 구조의 예시를 제시해요.
LLM에 지시사항과 예시, 샘플 대화 기록을 프롬프트로 넣어요.

// 예시 코드 — OpenAI 에이전트
// (자세한 예시는 LlamaIndexTS 저장소의 examples/agents/agent/openai.ts 참고)

코드를 실행하려면:

npx tsx example.ts

다음과 같은 출력을 기대할 수 있어요.

{
  result: '5 + 5 is 10. Then, 10 divided by 2 is 5.',
  state: {
    memory: Memory {
      messages: [Array],
      tokenLimit: 30000,
      shortTermTokenLimitRatio: 0.7,
      memoryBlocks: [],
      memoryCursor: 0,
      adapters: [Object]
    },
    scratchpad: [],
    currentAgentName: 'Agent',
    agents: [ 'Agent' ],
    nextAgentName: null
  }
}
Done

성능 최적화

토크나이징 속도

gpt-tokenizer를 설치하면 토크나이징이 60배 빨라져요 (Node.js 환경에서만).

npm i gpt-tokenizer

사용 가능할 때 LlamaIndex가 자동으로 활용합니다.

배포 가이드

배포 대상을 선택하면 돼요.

Server APIs & Backends
Serverless Functions
Next.js Applications
Troubleshooting

LLM/임베딩 프로바이더

OpenAI 이외의 다른 LLM·임베딩 프로바이더를 쓰려면 LLM API 문서와 임베딩 API 문서를 보면 돼요.

다음 단계

LlamaIndex.TS 배우기
코드 예시 보기

LlamaIndex.TS 설치하기