feat: production-level reliability, observability, and OpenAI compatibility improvements

[chottokun]

Summary

This pull request brings comprehensive production-grade improvements to the embedding and reranking API service.

Key Enhancements

1. OpenAI API Full Compatibility:
   • Added standard GET /v1/models listing embedding and reranking models (ModelList, ModelCard).
   • Supported dimensions parameter for Matryoshka models with automatic L2 re-normalization.
   • Supported encoding_format="base64" (IEEE 754 float32 little-endian).
2. High Availability & SRE:
   • Separated /health / /healthz (Liveness) and /ready (Readiness probe verifying GPU & loaded models).
   • Added in-flight request tracking with graceful shutdown drain middleware (SHUTDOWN_DRAIN_TIMEOUT_SECONDS), rejecting incoming requests with 503 Service Unavailable during draining.
   • Dynamic model unloading endpoint (POST /v1/models/unload) with GPU memory and GC reclamation.
   • Added PRELOAD_MODELS startup option to eliminate cold-start latency.
3. Observability & APM:
   • Structured JSON logging with X-Request-ID correlation across ContextVars.
   • Prometheus metrics (/metrics) with request counts, latency histograms, token usage (http_prompt_tokens_total), and batch size distribution (http_request_batch_size).
4. Security & DoS Defense:
   • Early payload size limit middleware (MAX_PAYLOAD_SIZE = 32MB, returning 413 Payload Too Large).
   • Token-bucket / sliding-window RateLimiter middleware (RATE_LIMIT_PER_MINUTE, returning 429 Too Many Requests with Retry-After).
   • DNS Rebinding and TOCTOU attack mitigation via SafeNetworkBackend IP pinning.
   • Enforced uv audit, gitleaks, and repo-wide linting in GitHub Actions CI.
5. Inference & Concurrency Optimization:
   • Completely asynchronous TEI proxy using pooled httpx.AsyncClient.
   • Heterogeneous batch tensor encoding in VisualizedBGEEmbeddingModel.encode_multimodal.
   • Configurable mixed-precision inference via TORCH_DTYPE (bfloat16, float16, float32) and torch.autocast.

Test Coverage

• 174 unit and integration tests passing (100% success, 0 failures)
• Complete end-to-end live execution and header/response verification.

[chottokun]

🧪 実動作検証エビデンス (Live Execution Evidence)

本PRに含まれる主要機能の実動テストおよび目視確認結果です。全174件の自動テストが通過していることに加え、実リクエストによる各エンドポイントの挙動を確認済みです。

1. レートリミット (429 Too Many Requests & Retry-After)

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{"detail": "Too Many Requests"}

2. グレースフルシャットダウン (503 Service Unavailable)

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{"detail": "Server is shutting down. Please retry shortly."}

3. OpenAI 互換 dimensions (L2正規化) & base64

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": "3/n5v+O75T7b0wU/",
      "index": 0
    }
  ],
  "model": "cl-nagoya/ruri-v3-small"
}

• Base64 デコード (float32 x 3): [-0.7259006, 0.44686416, -0.5224346]
• L2 ノルム: 1.0000000

4. Prometheus メトリクス (/metrics)

http_prompt_tokens_total{model="cl-nagoya/ruri-v3-30m"} 10.0
http_request_batch_size_bucket{endpoint="/v1/embeddings",le="2.0"} 1.0

[chottokun]

🚀 追加実装・検証完了報告 (Commit: 2b3099f)

Jules との並行実行タスクを統合し、プロダクション向けインフラ定義および API ドキュメンテーションの強化を実施しました。

---

1. Kubernetes 本番デプロイメントマニフェスト (deploy/kubernetes/)

• deployment.yaml: Liveness Probe (/healthz)、Readiness Probe (/ready)、Prometheus スクレイプ定義 (prometheus.io/scrape: "true")、CPU/Memory の requests/limits 設定。
• service.yaml: ClusterIP サービス定義 (Port 8000)。
• hpa.yaml: HorizontalPodAutoscaler による CPU (75%) / Memory (80%) 負荷ベースの水平自動スケール (1〜5 Pod)。
• docs/deployment.md: デプロイ手順・HPA 動作確認・メトリクス連携ガイド。

2. OpenAPI 3.x / Swagger UI (/docs) の完全スキーマ拡充

• 各エンドポイントにタグ (Embeddings, Reranking, Models, Health, Metrics)、summary、description を付与。
• 標準エラーレスポンス (400, 401, 413, 429, 503) をスキーマに明示化。
• EmbeddingRequest および RerankRequest に実用的な日本語リクエスト例 (json_schema_extra) を追加。

3. テスト & 静的解析

• uv run pytest: 全 175 件 PASS (回帰・デグレ 0 件)
• uv run ruff check . & uv run ruff format --check src/: All checks passed (All files cleanly formatted)

[chottokun]

🚀 追加実装・検証完了報告 (Commit: de0b758)

ご指示いただいた4項目（不要ブランチ削除、推論セマフォ制御、マルチAPIキー認証、高並行負荷テスト）を完了しました。

---

1. 不要なリモートブランチの整理・削除 (GitHub)

• マージ済みおよび古い検証用の 9 つのリモートブランチを安全に削除（git remote prune origin 完了）。
• 現在のリモートブランチは main と PR対象の feature/production-level-improvements のみにクリーンアップ。

2. 推論同時実行数のセマフォ制御 (MAX_CONCURRENT_INFERENCES)

• asyncio.Semaphore(MAX_CONCURRENT_INFERENCES) により、同時推論処理の上限数を厳格に制御（デフォルト: 4）。
• キュー待機タイムアウト (INFERENCE_SEMAPHORE_TIMEOUT_SECONDS, 30s) を設定し、過負荷滞留時は 503 Service Unavailable を返却して GPU/CPU の飽和・CUDA OOM を防止。
• 単体テスト: src/tests/test_concurrency_edge.py に検証テストを追加。

3. クライアント別 API Key 管理 & 個別レート制限 (API_KEYS_MAP)

• API_KEYS 環境変数（カンマ区切りまたは JSON: {"key1": 120, "key2": 300}）をサポート。
• タイミング攻撃防御のため、secrets.compare_digest による定数時間比較を全キーに適用。
• RateLimiter ミドルウェアで各キーごとの個別レート制限を自動適用。
• 単体テスト: src/tests/test_auth.py および src/tests/test_rate_limit.py に検証テストを追加。

4. 高並行負荷テストの実施 (50リクエスト・10並行ワーカー)

• 成功率: 100.0% (50/50 リクエスト 200 OK)
• スループット: 3.42 req/sec (平均レイテンシ: 2,875ms, P50: 874ms)
• セマフォ制限下でもデッドロック・クラッシュ・500エラー発生ゼロを確認。

5. 自動テスト & 静的解析

• uv run pytest: 全 178 件 PASS (100% 成功、0 failure)
• uv run ruff check . & uv run ruff format --check src/: **All checks passeduv run pytest: **全 178 件 PASS ( 100% 成功、0 failure ) ***

[chottokun]

🚀 追加検証・リファクタ完了報告 (Commit: a0852d7)

Jules セッション 4603548394163471290（OpenAPIドキュメント拡充）の成果を精査し、PRの整合性と既存の高度な実装を保護しながら差分を厳格に統合・検証しました。

---

1. Jules セッション 4603548394163471290 の精査と統合

• 成果の統合: エラー時のレスポンスモデルとして ErrorResponse を定義し、/v1/embeddings および /v1/rerank の 400, 401, 413, 429, 503 レスポンス定義へバインド（Swagger UI 上で詳細なエラースキーマがプレビュー可能に）。
• デグレ防止: Jules 側の差分が古いベースブランチに基づいていたため、ローカルで先行実装済みの dimensions（Matryoshka 次元削減）、encoding_format="base64"、およびマルチAPIキー認証を上書き・破壊しないよう、安全に選択的統合を実施。

2. セマフォ制御のマルチイベントループ耐性強化 (AsyncThreadSemaphore)

• マルチスレッド環境や個別イベントループで動作するテスト・クライアントにおいても、イベントループ競合 (RuntimeError: is bound to a different event loop) を引き起こさない AsyncThreadSemaphore を導入。
• 高並行下でも非同期性を維持したまま、確実なスレッドセーフティと推論同時実行制限を両立。

3. 品質検証結果

• uv run pytest: 全 178 件 PASS (回帰・デグレ 0 件)
• uv run ruff check . & uv run ruff format --check src/: **All checks passeduv run pytest: **全 178 件 PASS ( 回帰・デグレ 0 件 ) ***