T-CREATOR

LlamaIndex セットアップ完全ガイド:Python/Node・API キー・環境変数まで

LlamaIndex セットアップ完全ガイド:Python/Node・API キー・環境変数まで

LlamaIndex を使った開発を始めたいけれど、セットアップ手順がわからず困っていませんか?公式ドキュメントを読んでも、Python と Node.js のどちらを選べばいいのか、API キーの設定方法や環境変数の管理はどうすればいいのか、迷ってしまうことも多いでしょう。

本記事では、LlamaIndex のセットアップを Python と Node.js の両方の環境で解説し、API キーの取得から環境変数の設定まで、初心者の方でもスムーズに始められるよう丁寧にご説明します。

背景

LlamaIndex とは

LlamaIndex は、大規模言語モデル(LLM)を活用したアプリケーション開発を支援するデータフレームワークです。独自のデータと LLM を組み合わせ、質問応答システムやチャットボット、検索エンジンなどを構築できます。

以下の図は、LlamaIndex を使ったアプリケーションの基本的なデータフローを示しています。

mermaidflowchart LR
  user["ユーザー"] -->|質問| app["LlamaIndex<br/>アプリケーション"]
  app -->|クエリ| index["インデックス<br/>(データ構造)"]
  index -->|検索結果| llm["LLM<br/>(GPT-4等)"]
  llm -->|回答生成| app
  app -->|回答| user
  data["データソース<br/>(PDF/DB/API)"] -->|読み込み| index

このように、LlamaIndex はデータの取り込みからインデックス化、LLM への問い合わせまでを一貫して処理します。

Python 版と Node.js 版の違い

LlamaIndex には Python 版(llama-index)と Node.js 版(llamaindex)の 2 つの実装があります。どちらも同じコンセプトで設計されていますが、以下の特徴があります。

#項目Python 版Node.js 版
1パッケージ名llama-indexllamaindex
2機能の充実度★★★★★★★★☆☆
3ドキュメント豊富基本的
4エコシステム機械学習系と相性良Web 開発と統合しやすい
5開発スピード研究・実験向きプロダクション向き

Python 版は機能が豊富で、研究開発やプロトタイピングに適しています。一方、Node.js 版は Web アプリケーションとの統合がしやすく、Next.js や Express との組み合わせに向いているでしょう。

API キーと環境変数の重要性

LlamaIndex は OpenAI や Anthropic などの LLM サービスを利用するため、API キーが必須です。API キーはサービス利用の認証情報であり、適切に管理しないと以下のリスクがあります。

  • コードリポジトリに誤ってコミットしてしまう
  • 第三者に不正利用される
  • 予期せぬ課金が発生する

環境変数を使った管理方法を理解することで、これらのリスクを回避できます。

課題

セットアップ時の一般的な問題

LlamaIndex のセットアップでは、以下のような課題に直面することがあります。

mermaidflowchart TD
  start["セットアップ開始"] --> q1{"言語は<br/>Python? Node?"}
  q1 -->|Python| p1["pip install"]
  q1 -->|Node.js| n1["yarn add"]
  p1 --> q2{"API キーは<br/>取得済み?"}
  n1 --> q2
  q2 -->|いいえ| error1["エラー:<br/>認証失敗"]
  q2 -->|はい| q3{"環境変数は<br/>設定済み?"}
  q3 -->|いいえ| error2["エラー:<br/>API キー未検出"]
  q3 -->|はい| success["セットアップ完了"]
  error1 --> stop1["課題1:<br/>API キー取得"]
  error2 --> stop2["課題2:<br/>環境変数設定"]

主な課題をまとめると、以下の 3 点です。

  1. 環境選択の迷い: Python と Node.js のどちらを選ぶべきか判断が難しい
  2. API キー取得の複雑さ: OpenAI や他のサービスでの API キー取得手順がわかりにくい
  3. 環境変数設定の不明瞭さ: .env ファイルの作り方や変数名がわからない

これらの課題を一つずつ解決していきましょう。

解決策

環境選択の指針

プロジェクトの目的に応じて、以下の基準で選択することをおすすめします。

Python を選ぶべきケース

  • データサイエンスや機械学習の知識がある
  • Jupyter Notebook で実験的に開発したい
  • pandas や NumPy などの Python ライブラリを活用したい
  • 最新機能や豊富なドキュメントを利用したい

Node.js を選ぶべきケース

  • Next.js や Express で Web アプリケーションを開発している
  • TypeScript で型安全な開発をしたい
  • フロントエンドとバックエンドを JavaScript/TypeScript で統一したい
  • API サーバーとして LlamaIndex を組み込みたい

以降のセクションでは、両方の環境のセットアップ手順を解説します。

API キー取得の統一手順

LlamaIndex で最も一般的に使われる OpenAI の API キーを例に、取得手順を説明します。

mermaidflowchart LR
  step1["OpenAI サイト<br/>アクセス"] --> step2["アカウント作成/<br/>ログイン"]
  step2 --> step3["API Keys<br/>ページへ移動"]
  step3 --> step4["Create new<br/>secret key"]
  step4 --> step5["キーをコピー<br/>(1度のみ表示)"]
  step5 --> step6["安全に保存"]

具体的な手順は以下の通りです。

  1. OpenAI Platform にアクセス
  2. アカウントを作成するか、既存アカウントでログイン
  3. 右上のアカウントメニューから「API keys」を選択
  4. 「Create new secret key」ボタンをクリック
  5. キー名を入力(例:llamaindex-dev)して作成
  6. 表示されたキーをコピー(この画面は 1 度しか表示されません)

取得した API キーは、テキストファイルやパスワード管理ツールに安全に保存しておきましょう。

環境変数管理のベストプラクティス

環境変数を使うことで、API キーをコードから分離し、セキュリティを高められます。以下の原則を守ることが重要です。

  • .env ファイルをリポジトリにコミットしない(.gitignore に追加)
  • .env.example ファイルで必要な変数名を共有
  • 本番環境では環境変数を直接設定(.env ファイルを使わない)

具体例

Python 環境のセットアップ

Python 環境での LlamaIndex セットアップを段階的に進めていきます。

Python バージョンの確認

まず、Python 3.8 以上がインストールされているか確認しましょう。

bashpython --version
# または
python3 --version

Python 3.8.0 以上が表示されれば OK です。インストールされていない場合は、Python 公式サイトからダウンロードしてください。

仮想環境の作成

プロジェクトごとに独立した環境を作ることで、依存関係の競合を防げます。

bash# プロジェクトディレクトリを作成
mkdir llamaindex-python-app
cd llamaindex-python-app

# 仮想環境を作成
python -m venv venv

この手順で venv ディレクトリが作成され、その中に独立した Python 環境が構築されます。

仮想環境の有効化

作成した仮想環境を有効化します。OS によってコマンドが異なるので注意しましょう。

bash# macOS / Linux の場合
source venv/bin/activate

# Windows の場合
venv\Scripts\activate

有効化されると、コマンドプロンプトの先頭に (venv) が表示されます。

LlamaIndex のインストール

仮想環境を有効化した状態で、LlamaIndex をインストールします。

bashpip install llama-index

このコマンドで、LlamaIndex 本体と必要な依存パッケージが自動的にインストールされます。インストールには数分かかる場合があるでしょう。

環境変数ファイルの作成

プロジェクトルートに .env ファイルを作成し、API キーを設定します。

bashtouch .env

.env ファイルをテキストエディタで開き、以下の内容を記述してください。

envOPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

sk-proj- の後には、先ほど取得した実際の API キーを貼り付けます。

.gitignore の設定

API キーが誤ってリポジトリにコミットされないよう、.gitignore ファイルを作成します。

gitignore# 仮想環境
venv/

# 環境変数ファイル
.env

# Python キャッシュ
__pycache__/
*.pyc
*.pyo
*.pyd

# IDE 設定
.vscode/
.idea/

この設定により、機密情報や不要なファイルが Git 管理から除外されます。

環境変数の読み込み

Python で環境変数を読み込むには、python-dotenv パッケージを使用します。

bashpip install python-dotenv

これで .env ファイルから環境変数を自動的に読み込めるようになりました。

動作確認用スクリプト

セットアップが正しく完了したか確認するため、簡単なスクリプトを作成します。

python# main.py
import os
from dotenv import load_dotenv

# .env ファイルから環境変数を読み込み
load_dotenv()

# API キーが読み込まれているか確認
api_key = os.getenv("OPENAI_API_KEY")
if api_key:
    print("✓ API キーが正しく読み込まれました")
    print(f"キーの最初の10文字: {api_key[:10]}...")
else:
    print("✗ API キーが見つかりません")

このスクリプトは、環境変数が正しく設定されているか確認するためのものです。API キーの全体を表示せず、最初の 10 文字のみを表示することでセキュリティに配慮しています。

LlamaIndex の初期化

実際に LlamaIndex を使った簡単なコードを書いてみましょう。

python# app.py
import os
from dotenv import load_dotenv
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 環境変数を読み込み
load_dotenv()

まず、必要なモジュールをインポートし、環境変数を読み込みます。VectorStoreIndex はデータのインデックス化を行い、SimpleDirectoryReader はディレクトリからドキュメントを読み込むクラスです。

python# サンプルデータの読み込み
# (data/ ディレクトリにテキストファイルがあると仮定)
def load_data():
    """
    data/ ディレクトリからドキュメントを読み込む
    Returns:
        list: Document オブジェクトのリスト
    """
    try:
        documents = SimpleDirectoryReader("data").load_data()
        print(f"✓ {len(documents)} 件のドキュメントを読み込みました")
        return documents
    except Exception as e:
        print(f"✗ データ読み込みエラー: {e}")
        return None

この関数は data​/​ ディレクトリからテキストファイルを読み込みます。エラーハンドリングも含めることで、ファイルが見つからない場合でも適切なメッセージを表示できますね。

python# インデックスの作成
def create_index(documents):
    """
    ドキュメントからベクトルインデックスを作成
    Args:
        documents: Document オブジェクトのリスト
    Returns:
        VectorStoreIndex: 作成されたインデックス
    """
    try:
        index = VectorStoreIndex.from_documents(documents)
        print("✓ インデックスを作成しました")
        return index
    except Exception as e:
        print(f"✗ インデックス作成エラー: {e}")
        return None

ドキュメントをベクトル化してインデックスを作成する処理です。この処理で、文書の内容が数値ベクトルに変換され、効率的な検索が可能になります。

python# メイン処理
def main():
    # データ読み込み
    documents = load_data()
    if not documents:
        return

    # インデックス作成
    index = create_index(documents)
    if not index:
        return

    # クエリエンジンの作成
    query_engine = index.as_query_engine()

    # 質問応答のテスト
    response = query_engine.query("ドキュメントの内容を要約してください")
    print(f"\n回答:\n{response}")

if __name__ == "__main__":
    main()

メイン処理では、データの読み込み、インデックスの作成、そして質問応答を実行します。各ステップでエラーチェックを行うことで、堅牢なコードになっているでしょう。

テストデータの準備

動作確認のため、サンプルデータを用意します。

bash# data ディレクトリを作成
mkdir data

data​/​sample.txt ファイルを作成し、以下のような内容を記述してください。

textLlamaIndex は、大規模言語モデルを活用したアプリケーション開発を支援するフレームワークです。

主な機能:
- データの取り込みとインデックス化
- ベクトル検索による効率的な情報検索
- LLM との統合による質問応答システムの構築

Python と Node.js の両方で利用可能で、様々なデータソースに対応しています。

これで、実際に LlamaIndex が動作する環境が整いました。

実行とトラブルシューティング

作成したスクリプトを実行してみましょう。

bashpython app.py

正常に動作すれば、以下のような出力が表示されます。

text✓ 1 件のドキュメントを読み込みました
✓ インデックスを作成しました

回答:
LlamaIndex は大規模言語モデルを活用したアプリケーション開発フレームワークで、データの取り込み、インデックス化、ベクトル検索、質問応答システムの構築などの機能を提供します。Python と Node.js で利用可能です。

よくあるエラーと解決方法

#エラーコード原因解決方法
1AuthenticationError: 401API キーが無効.env ファイルの API キーを確認
2ModuleNotFoundErrorパッケージ未インストールpip install llama-index python-dotenv を実行
3FileNotFoundError: data​/​データディレクトリがないmkdir data でディレクトリを作成
4RateLimitError: 429API 呼び出し制限超過しばらく待ってから再実行

Node.js 環境のセットアップ

次に、Node.js 環境での LlamaIndex セットアップを進めます。

Node.js バージョンの確認

Node.js 18 以上がインストールされているか確認します。

bashnode --version

v18.0.0 以上が表示されれば問題ありません。インストールされていない場合は、Node.js 公式サイトからダウンロードしてください。

プロジェクトの初期化

新しいプロジェクトディレクトリを作成し、初期化します。

bash# プロジェクトディレクトリを作成
mkdir llamaindex-node-app
cd llamaindex-node-app

# package.json を作成
yarn init -y

この手順で package.json ファイルが作成され、Node.js プロジェクトとして認識されます。

TypeScript の設定

型安全な開発のため、TypeScript を導入しましょう。

bashyarn add -D typescript @types/node ts-node

開発時に必要なパッケージとして、TypeScript 本体と型定義ファイル、実行環境をインストールします。

tsconfig.json の作成

TypeScript の設定ファイルを作成します。

bashnpx tsc --init

生成された tsconfig.json を以下のように編集してください。

json{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

この設定により、src​/​ ディレクトリのソースコードが dist​/​ ディレクトリにコンパイルされます。最新の JavaScript 機能を使いながら、型チェックも厳格に行えるでしょう。

LlamaIndex のインストール

Node.js 版の LlamaIndex をインストールします。

bashyarn add llamaindex

このパッケージには、LlamaIndex のコア機能と OpenAI との連携機能が含まれています。

環境変数管理パッケージの追加

.env ファイルを読み込むため、dotenv をインストールします。

bashyarn add dotenv
yarn add -D @types/dotenv

本体パッケージと TypeScript の型定義の両方をインストールすることで、型安全に環境変数を扱えますね。

.env ファイルの作成

プロジェクトルートに .env ファイルを作成します。

bashtouch .env

.env ファイルに API キーを記述しましょう。

envOPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Python 版と同じ形式で、取得した API キーを設定します。

.gitignore の設定

Node.js プロジェクト用の .gitignore を作成します。

gitignore# 依存パッケージ
node_modules/

# ビルド成果物
dist/

# 環境変数ファイル
.env

# ログファイル
*.log

# IDE 設定
.vscode/
.idea/

# OS 固有ファイル
.DS_Store
Thumbs.db

これにより、不要なファイルや機密情報がリポジトリにコミットされるのを防げます。

ディレクトリ構成の準備

ソースコードとデータを整理するため、必要なディレクトリを作成します。

bashmkdir src
mkdir data

src​/​ には TypeScript のソースコードを、data​/​ にはサンプルデータを配置します。

動作確認用スクリプト

環境変数が正しく読み込まれるか確認するスクリプトを作成しましょう。

typescript// src/check-env.ts
import * as dotenv from 'dotenv';

// .env ファイルを読み込み
dotenv.config();

// API キーの確認
const apiKey = process.env.OPENAI_API_KEY;

if (apiKey) {
  console.log('✓ API キーが正しく読み込まれました');
  console.log(
    `キーの最初の10文字: ${apiKey.substring(0, 10)}...`
  );
} else {
  console.log('✗ API キーが見つかりません');
  console.log(
    '`.env` ファイルに OPENAI_API_KEY を設定してください'
  );
}

このスクリプトは、環境変数の読み込みが正常に動作するかテストします。セキュリティを考慮し、API キーの一部のみを表示しているでしょう。

実行スクリプトの追加

package.json にスクリプトを追加して、実行を簡単にします。

json{
  "scripts": {
    "check": "ts-node src/check-env.ts",
    "dev": "ts-node src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

これで yarn check コマンドで環境変数の確認、yarn dev で開発実行ができます。

動作確認

環境変数の読み込みをテストしてみましょう。

bashyarn check

正常に動作すれば、以下のような出力が得られます。

text✓ API キーが正しく読み込まれました
キーの最初の10文字: sk-proj-ab...

LlamaIndex の実装

実際に LlamaIndex を使ったコードを書いていきます。

typescript// src/index.ts
import * as dotenv from 'dotenv';
import fs from 'fs/promises';
import { Document, VectorStoreIndex } from 'llamaindex';

// 環境変数を読み込み
dotenv.config();

必要なモジュールをインポートし、環境変数を読み込みます。Document はテキストデータを表すクラス、VectorStoreIndex はインデックスを管理するクラスです。

typescript/**
 * データファイルを読み込んで Document オブジェクトに変換
 */
async function loadData(): Promise<Document[]> {
  try {
    const content = await fs.readFile(
      'data/sample.txt',
      'utf-8'
    );
    const document = new Document({ text: content });
    console.log('✓ ドキュメントを読み込みました');
    return [document];
  } catch (error) {
    console.error('✗ データ読み込みエラー:', error);
    return [];
  }
}

ファイルシステムからテキストファイルを非同期で読み込み、LlamaIndex の Document 形式に変換します。エラーハンドリングも実装することで、ファイルが存在しない場合でも適切に処理できますね。

typescript/**
 * ドキュメントからインデックスを作成
 */
async function createIndex(
  documents: Document[]
): Promise<VectorStoreIndex> {
  try {
    const index = await VectorStoreIndex.fromDocuments(
      documents
    );
    console.log('✓ インデックスを作成しました');
    return index;
  } catch (error) {
    console.error('✗ インデックス作成エラー:', error);
    throw error;
  }
}

ドキュメントをベクトル化してインデックスを作成する非同期関数です。この処理により、テキストが検索可能な形式に変換されます。

typescript/**
 * 質問応答を実行
 */
async function queryIndex(
  index: VectorStoreIndex,
  question: string
) {
  try {
    const queryEngine = index.asQueryEngine();
    const response = await queryEngine.query({
      query: question,
    });
    console.log(`\n質問: ${question}`);
    console.log(`回答:\n${response.toString()}`);
  } catch (error) {
    console.error('✗ クエリ実行エラー:', error);
  }
}

作成したインデックスに対して質問を投げ、LLM による回答を取得する関数です。質問と回答を見やすく表示します。

typescript/**
 * メイン処理
 */
async function main() {
  console.log('LlamaIndex セットアップテスト開始\n');

  // データ読み込み
  const documents = await loadData();
  if (documents.length === 0) {
    console.log('ドキュメントが見つかりません');
    return;
  }

  // インデックス作成
  const index = await createIndex(documents);

  // 質問応答のテスト
  await queryIndex(
    index,
    'LlamaIndex の主な機能を教えてください'
  );
}

// プログラム実行
main().catch(console.error);

メイン処理では、データの読み込み、インデックスの作成、質問応答を順番に実行します。非同期処理のエラーもキャッチして表示する仕組みになっています。

テストデータの準備

Python 版と同じサンプルデータを data​/​sample.txt に作成してください。

textLlamaIndex は、大規模言語モデルを活用したアプリケーション開発を支援するフレームワークです。

主な機能:
- データの取り込みとインデックス化
- ベクトル検索による効率的な情報検索
- LLM との統合による質問応答システムの構築

Python と Node.js の両方で利用可能で、様々なデータソースに対応しています。

これで、実際に LlamaIndex が動作する環境が整いました。

実行とトラブルシューティング

作成したアプリケーションを実行してみましょう。

bashyarn dev

正常に動作すれば、以下のような出力が得られます。

textLlamaIndex セットアップテスト開始

✓ ドキュメントを読み込みました
✓ インデックスを作成しました

質問: LlamaIndex の主な機能を教えてください
回答:
LlamaIndex の主な機能は、データの取り込みとインデックス化、ベクトル検索による効率的な情報検索、LLM との統合による質問応答システムの構築です。Python と Node.js の両方で利用可能です。

Node.js 版でよくあるエラーと解決方法

#エラーメッセージ原因解決方法
1Error: Cannot find module 'llamaindex'パッケージ未インストールyarn add llamaindex を実行
2TypeError: Cannot read property 'OPENAI_API_KEY'環境変数が読み込まれていないdotenv.config() を先頭に追加
3Error: ENOENT: no such file or directoryデータファイルが存在しないdata​/​sample.txt を作成
4OpenAI API error: 401 UnauthorizedAPI キーが無効OpenAI Platform でキーを確認

環境変数の本番環境設定

開発環境では .env ファイルを使いますが、本番環境では直接環境変数を設定する方が安全です。

Vercel での設定

Next.js アプリを Vercel にデプロイする場合の設定方法です。

  1. Vercel のプロジェクト設定画面を開く
  2. 「Environment Variables」セクションに移動
  3. 以下の変数を追加
textKey: OPENAI_API_KEY
Value: sk-proj-xxxxxxxxxxxxxxxx
Environment: Production, Preview, Development

保存後、次回のデプロイから環境変数が適用されます。

Docker での設定

Docker コンテナで実行する場合、docker-compose.yml で環境変数を設定します。

yamlversion: '3.8'
services:
  app:
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    env_file:
      - .env

この設定により、ホスト側の環境変数やファイルからコンテナに変数を渡せます。

AWS Lambda での設定

AWS Lambda で実行する場合、Lambda の設定画面から環境変数を追加します。

  1. Lambda 関数の設定画面を開く
  2. 「環境変数」セクションに移動
  3. 「編集」をクリックして以下を追加
textキー: OPENAI_API_KEY
値: sk-proj-xxxxxxxxxxxxxxxx

暗号化オプションを有効にすることで、より安全に管理できるでしょう。

複数の LLM プロバイダーの設定

OpenAI 以外の LLM サービスを使う場合の環境変数設定例です。

Anthropic Claude の設定

envANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Python での使用例です。

pythonimport os
from llama_index.llms.anthropic import Anthropic
from llama_index.core import Settings

# Claude を LLM として設定
Settings.llm = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

Azure OpenAI の設定

envAZURE_OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-02-15-preview

TypeScript での使用例です。

typescriptimport { AzureOpenAI } from 'llamaindex';

const llm = new AzureOpenAI({
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  endpoint: process.env.AZURE_OPENAI_ENDPOINT,
  apiVersion: process.env.AZURE_OPENAI_API_VERSION,
});

Hugging Face の設定

envHUGGINGFACE_API_KEY=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

複数のプロバイダーを同時に設定しておくことで、用途に応じて切り替えられます。

まとめ

本記事では、LlamaIndex のセットアップ手順を Python と Node.js の両環境で詳しく解説しました。

重要なポイント

  • Python 版は機能が豊富で研究開発向き、Node.js 版は Web 開発との統合が容易
  • OpenAI API キーは OpenAI Platform から取得し、1 度しか表示されないため安全に保存
  • 環境変数を使って API キーをコードから分離し、.gitignore で保護
  • .env ファイルは開発環境のみで使用し、本番環境では直接環境変数を設定
  • エラーが発生した場合は、API キー、パッケージのインストール、データファイルの存在を確認

セットアップが完了したら、実際にデータを読み込んで質問応答システムを構築してみましょう。LlamaIndex は柔軟性が高く、PDF ファイルやデータベース、API からのデータ取り込みにも対応しています。

環境変数の管理を適切に行うことで、安全かつ効率的な開発が可能になります。本記事で紹介した手順を参考に、ぜひ LlamaIndex を活用したアプリケーション開発を始めてみてください。

関連リンク