./knowledge-base/README.md
# 🗄️ knowledge-base
**時代考証アシストシステム** の知識ベース・検索基盤モジュールです。
歴史資料の画像を AI で解析し、セマンティック検索を可能にします。
> 💡 **開発フローや CI/CD の仕組みについては [ルートの README](../README.md) を参照してください。**
> コードを `main` ブランチにプッシュするだけで、AWS への自動デプロイが完了します。
---
## 🎯 主要機能
| 機能 | 内容 |
| ---- | ---- |
| 📸 画像解析 | AI が画像を読み取り、内容・年代・タグを自動抽出 |
| 🔍 セマンティック検索 | キーワードの意味から関連資料を検索 |
| 🏷️ フィルタリング | 時代・ジャンル・タグで絞り込み |
| 📦 一括処理 | 複数資料のまとめてアップロード |
---
## 🏗️ システム構成
```
ブラウザ（フロントエンド）
│
▼
CloudFront（CDN）
│
▼
API Gateway（HTTPS API）
│
┌────┴───────────────────┐
▼ ▼
upload-handler search-api
│ │
▼ ▼
image-analyzer OpenSearch
（Claude Sonnet） （ベクトル検索DB）
│
▼
embedding-generator
（Bedrock Titan）
│
▼
OpenSearch
```
### 使用サービス一覧
| サービス | 用途 |
| -------- | ---- |
| AWS Lambda | サーバーレス関数（6つ） |
| Amazon OpenSearch | ベクトル検索エンジン |
| Amazon S3 | 画像・プロンプト・フロントエンド配信 |
| Amazon DynamoDB | 処理ステータス管理 |
| Amazon SQS | 非同期処理キュー |
| Amazon API Gateway | HTTPS API |
| Amazon CloudFront | CDN 配信 |
| AWS CDK | インフラをコードで定義・管理 |
---
## ⚡ Lambda 関数の役割
| 関数名 | 役割 |
| ------ | ---- |
| `upload-handler` | 画像アップロードの受け付け・SQS へのキュー投入 |
| `image-analyzer` | Claude Sonnet による画像解析（OCR・内容抽出） |
| `embedding-generator` | Bedrock Titan によるベクトル（埋め込み）生成・OpenSearch への登録 |
| `search-api` | セマンティック検索の実行 |
| `bulk-processor` | 複数資料の一括アップロード処理 |
| `dlq-processor` | 失敗したジョブの再処理 |
---
## 📁 ディレクトリ構造
```
knowledge-base/
├── cdk/ # インフラ定義（AWS CDK / TypeScript）
│ ├── bin/
│ │ └── historical-research.ts # CDK エントリーポイント
│ ├── lib/
│ │ └── historical-research-stack.ts # メインスタック定義
│ └── cdk.json
├── lambda/ # Lambda 関数（Python）
│ ├── layers/common/ # 共通ライブラリレイヤー
│ ├── upload-handler/
│ ├── image-analyzer/
│ ├── embedding-generator/
│ ├── search-api/
│ ├── bulk-processor/
│ └── dlq-processor/
├── frontend/ # フロントエンド（React / Vite）
├── prompts/ # AI プロンプトファイル（S3 で管理）
│ ├── image-analysis/
│ │ ├── main.txt # 画像解析プロンプト
│ │ └── json-schema.json # 出力スキーマ定義
│ └── master/
│ └── era-list.json # 時代区分マスタ
└── docs/ # 詳細ドキュメント
```
> 📝 **プロンプトファイル（`prompts/`）の変更も `main` にプッシュするだけで自動反映されます。**
---
## 🛠️ ローカル開発
### CDK の差分を確認する
インフラの変更を本番に適用する前に、差分を事前確認できます。
```bash
cd knowledge-base/cdk
npm install # 初回のみ
cdk diff # 現在の AWS 環境との差分を表示
```
> ⚠️ 実際のデプロイは `cdk deploy` を直接実行しないでください。
> **`main` ブランチへのプッシュで CI/CD が自動実行**します。
---
## 🔌 API エンドポイント
API Gateway のエンドポイント URL はデプロイログ（[Actions タブ](https://github.com/nhk-ds/HistoricalAccuracy/actions)）から確認できます。
### 📸 画像アップロード
```
POST /prod/process/upload
```
```json
{
"document_id": "doc_001",
"page_number": 1,
"metadata": {
"title": "昭和の台所",
"era": "昭和40年代（1956年～1965年）",
"genre": ["生活", "住宅"],
"tags": ["台所", "家電"]
},
"image_data": "<base64 エンコード済み画像>"
}
```
### 🔍 セマンティック検索
```
POST /prod/search
```
```json
{
"query": "昭和時代の台所",
"filters": {
"era": "昭和40年代（1956年～1965年）"
},
"page": 1,
"page_size": 20
}
```
### 📋 処理ステータス確認
```
GET /prod/process/status/{page_id}
```
---
## ⚠️ インフラの注意事項
### アクセス制限
API Gateway は以下の IP アドレスからのみアクセス可能です：
| 説明 | IP アドレス |
| ---- | ----------- |
| 社内ネットワーク | `133.127.0.0/16` |
| その他許可 IP | `118.238.211.181/32` |
| その他許可 IP | `125.196.69.242/32` |
### VPC 構成
Lambda 関数はプライベートサブネット内で動作します（既存 VPC `vpc-08d84efb87d052cf9` を使用）。
OpenSearch への直接アクセスが必要な場合は VPC 内からのみ可能です。
### API キー管理
LiteLLM の API キーは AWS Secrets Manager で管理しており、コードには含まれていません。
---
## 🆘 トラブルシューティング
| 症状 | 確認するポイント |
| ---- | --------------- |
| Lambda がタイムアウトする | CDK スタックのメモリ・タイムアウト設定を確認 |
| OpenSearch にアクセスできない | Security Group の設定・VPC 内からアクセスしているか確認 |
| プロンプトが反映されない | `prompts/` の変更が `main` にプッシュされているか確認 |
| デプロイが失敗する | [Actions タブ](https://github.com/nhk-ds/HistoricalAccuracy/actions) のログを確認 |
---
## 📖 詳細ドキュメント
| ドキュメント | 内容 |
| ------------ | ---- |
| [仕様書.md](仕様書.md) | システム全体の仕様 |
| [仕様書_基本機能.md](仕様書_基本機能.md) | 基本機能の詳細仕様 |
| [仕様書_基本機能_フロントエンド.md](仕様書_基本機能_フロントエンド.md) | フロントエンド仕様 |
| [仕様書_時代考証アシスト.md](仕様書_時代考証アシスト.md) | 時代考証アシスト機能仕様 |
| [開発引継ぎ.md](開発引継ぎ.md) | 開発引継ぎ情報 |
| [docs/AWS_ARCHITECTURE.md](docs/AWS_ARCHITECTURE.md) | AWS アーキテクチャ詳細 |
| [docs/opensearch-setup.md](docs/opensearch-setup.md) | OpenSearch セットアップ手順 |