SE の雑記

# 実装プラン: SQL Server 2025 Vector + RAG チャット (PHP/Laravel, Dev Container)

## 課題と方針
- SQL Server 2025 の vector データ型を用いた RAG チャットを、Laravel で構築する。
- 埋め込み済みデータ（wordpress.post_vector.v1, 1536 dims）を用い、Exact k-NN（VECTOR_DISTANCE / cosine）で検索。
- LLM 呼び出しは SQL Server の sp_invoke_external_rest_endpoint 経由で Azure OpenAI を利用（API キー）。
- UI はシンプルな Blade + API、認証なし、会話履歴は保存しない。

## 事前確認（前提）
- 外部 SQL Server 2025 に接続するための環境変数を .env と devcontainer.json で用意する。
- Azure OpenAI のエンドポイント/デプロイ名/API キーが準備済み。
- SQL Server 側で external rest endpoint が有効化され、必要な権限（EXECUTE ANY EXTERNAL ENDPOINT, etc.）が付与済み。

## 作業計画
- [x] 0. Git リポジトリ初期化
- [x] 1. リポジトリ初期状態の整理（ディレクトリ構成確認、README 方針確認）
- [x] 2. Dev Container 設定を作成/更新
  - PHP/Laravel 用イメージ
  - 拡張機能（PHP, SQL tools）
  - .env 連携（SQL/AOAI 接続情報）
  - 追加: Dev Container 起動時に PHP サーバー自動起動
- [x] 3. Laravel プロジェクト初期化（composer create-project）
- [x] 4. 設定: DB 接続（sqlsrv / PDO）
  - SQL Server 2025 へ接続できるドライバ設定
  - 接続テスト用のヘルスチェック
- [x] 5. DB 側の RAG クエリ設計
  - wordpress.post_vector (ID, v1 vector(1536)) を前提
  - wordpress.wp_posts の post_content と join
  - VECTOR_DISTANCE('cosine', @qv, v1) の検索 SQL
- [ ] 6. SQL Server に LLM 呼び出し用のストアド作成
  - ストアド作成スクリプト: database/sql/rag_completion.sql (DBで実行)
  - sp_invoke_external_rest_endpoint で Azure OpenAI chat/completions を呼び出し
  - 入出力 JSON の設計（質問 + 参照情報を prompt に組み込み）
- [x] 7. Laravel 側の API 実装
  - /api/chat: routes/api.php + app/Http/Controllers/ChatController.php
  - /api/chat: 質問受け取り → DB へ渡す → 回答+引用を返す
  - SQL Server ストアド実行の repository / service 層
- [x] 8. Blade UI 実装
  - /chat: resources/views/chat.blade.php + routes/web.php
  - チャットフォーム、回答表示、引用リスト
- [x] 9. エラーハンドリング/ログ/
  - /api/chat: 失敗時の詳細エラーをログ/JSONで返却
  - SQL 例外、REST エンドポイント失敗時の可視化
- [ ] 10. セットアップ手順と環境変数のドキュメント化
  - .env / devcontainer.json / SQL 権限設定
- [ ] 11. 動作確認
  - ローカル Dev Container 起動
  - 質問 → 検索 → 回答 + 引用の end-to-end

## 参考ドキュメント
- Vector data type / VECTOR_DISTANCE: https://learn.microsoft.com/en-us/sql/sql-server/ai/vectors?view=sql-server-ver17
- Vector data type 概要: https://learn.microsoft.com/en-us/sql/t-sql/data-types/vector-data-type?view=sql-server-ver17
- sp_invoke_external_rest_endpoint: https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-invoke-external-rest-endpoint-transact-sql?view=sql-server-ver17
- External REST endpoint 有効化: https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/server-configuration-options-sql-server?view=sql-server-ver17#configuration-options

## 注意点
- VECTOR_DISTANCE は exact 検索で、スケール次第では性能に注意。
- API キーは SQL Server の DATABASE SCOPED CREDENTIAL に保存。
- RAG のプロンプトは T-SQL で組み立て、出力 JSON を SQL でパースして返却。

SET NOCOUNT ON;
DECLARE @question NVARCHAR(4000) = :question;
DECLARE @top INT = :top;
DECLARE @vector VECTOR(1536) = AI_GENERATE_EMBEDDINGS(@question USE MODEL [text-embedding-ada-002]);
DROP TABLE IF EXISTS #tmp;
SELECT pv.ID,
    pv.post_title,
    pv.chunk,
    vs.distance 
INTO #tmp
FROM VECTOR_SEARCH(
        TABLE = wordpress.post_vector AS pv,
        COLUMN = v1,
        SIMILAR_TO = @vector,
        METRIC = 'cosine',
        TOP_N = @top
    ) AS vs
ORDER BY distance ASC;
SELECT t.ID,
    t.post_title,
    t.chunk,
    wp.guid,
    CAST(wp.post_content AS NVARCHAR(MAX)) AS post_content,
    t.distance
FROM #tmp t
    JOIN wordpress.wp_posts AS wp ON wp.ID = t.ID;

CREATE OR ALTER  PROCEDURE [dbo].[usp_aoai_response]
    @prompt NVARCHAR(MAX),
    @temperature FLOAT = 0.2,
    @model NVARCHAR(100) = N'gpt-5.1',
    @url NVARCHAR(max) = N'https://<Resource Name>.openai.azure.com/openai/responses?api-version=2025-04-01-preview',
    @credential NVARCHAR(100) = N'https://<Resource Name>.openai.azure.com'
AS
BEGIN
    SET NOCOUNT ON;

    DECLARE @payload NVARCHAR(MAX) =(
        SELECT
            @model AS model,
            @temperature AS temperature,
            payload AS input
        FROM
        (
            SELECT type,role, content
            FROM
            (
                SELECT
                    'message' AS type,
                    'system' AS role,
                    'あなたはテクニカルな内容をサポートするアシスタントです。' AS content
                UNION ALL
                SELECT 
                    'message' AS type,
	                'user' AS role,
                    STRING_ESCAPE(@prompt,'json') AS content
               
            ) AS T FOR JSON PATH
         ) AS T2(payload) FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
    )

    PRINT @payload;
    DECLARE @response NVARCHAR(MAX);
    DECLARE @retval INT;

    EXEC @retval = sp_invoke_external_rest_endpoint
        @url = @url,
        @method = 'POST',
        @payload = @payload,
        @credential = @credential,
        @timeout = 60,
        @headers = N'{"Content-Type":"application/json"}',
        @response = @response OUTPUT;

    SELECT
        @retval AS http_status,
        JSON_VALUE(@response, '$.result.choices[0].text') AS completion_text,
        @response AS response_json;
END

$ragPrompt = "あなたは参考情報に含まれる内容だけを使って、日本語で詳細に解説してに回答してください。\n" .
"参考情報にない内容は推測で補完しないでください。\n" .
"参考情報に質問への該当がない場合は、該当する情報が存在しない旨と理由を1文で回答してください。\n\n" .
"[参考情報]\n" . $context . "\n\n" .
"[質問]\n" . $question;

$generalPrompt = "以下の質問に、一般的な知識で日本語で簡潔に回答してください。\n" .
"参考情報は使わないでください。\n\n" .
"[質問]\n" . $question;