Configuring external storage
============================

AIDBパイプラインは、2種類のデータソースから読み取ることができます。

- **Postgresテーブル** — ``aidb.create_pipeline()`` の\ ``source``
  パラメーターを使用して、名前で直接テーブルを参照します。 :ref:`Creating pipelines <Creating pipelines>` 
  を参照してください。

- **外部ストレージボリューム** — S3互換オブジェクトストア、Google Cloud
  Storage、Azure、またはローカルファイルシステムをPGFSを介して接続します。このページの残りの部分では、これを設定する方法について説明します。

外部ストレージは、
PostgresファイルシステムPGFS拡張機能を介してアクセスされます。これは、外部ストレージを
*ストレージ場所* としてPostgresにマップします。
AIDBは、各保存場所を名前でパイプライン参照する *ボリューム*
でラップします。

その仕組み
----------

外部ストレージをAIDBパイプラインに接続することには、2つのオブジェクトが関係します。

- **PGFSストレージ場所** —
  外部ストレージプロバイダーのURI、資格情報、および接続オプションを定義します。
  :ref:`pgfs.create_storage_location() <Pipelines API reference>`  で作成されました。

- **AIDBボリューム** —
  PGFSストレージ場所をAIDBに接続します。データ形式Text、Image、Pdfと、保存場所内のオプションのサブパスを指定します。
  ``aidb.create_volume()`` で作成されました。

ボリュームが存在したら、Postgresテーブル名と同様に、\ ``aidb.create_pipeline()``
の\ ``source`` として参照します。

!!!注
ストレージの場所を作成する前に、PGFS拡張機能をインストールする必要があります。
:ref:`Configuring AIDB <Configuring AIDB>` を参照してください。

ステップ1保存場所を作成する
---------------------------

``pgfs.create_storage_location()``
を使用して、外部ストレージへの接続を定義します。 ``uri``
パラメーターは、ストレージバックエンドとパスを識別します。 ``options``
JSONBオブジェクトは、リージョンや資格情報などのプロバイダー固有の設定を保持します。

S3互換オブジェクトストア
^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: sql

   - - Private S3 bucket with credentials
   SELECT pgfs.create_storage_location(
       name    => my_s3_location,
       uri     => s3://my-bucket/my-folder,
       options => {"region": "us-east-1", "access_key_id": "<key>", "secret_access_key": "<secret>"}
   );

   - - Public S3 bucket (no credentials required)
   SELECT pgfs.create_storage_location(
       name    => my_public_bucket,
       uri     => s3://aidb-rag-app,
       options => {"region": "eu-central-1", "skip_signature": "true"}
   );

ローカルファイルシステム
^^^^^^^^^^^^^^^^^^^^^^^^

ローカルファイルシステムアクセスの場合、保存場所を作成する前に\ ``postgresql.conf``
で許可されるベースパスを宣言します。
PGFSは、セキュリティのためにこれらのパスへのアクセスを制限します。

.. code:: ini


   #  postgresql.conf

   pgfs.allowed_local_fs_paths = /tmp/pgfs

Postgresを再起動した後、\ ``file://``
URIを使用して保存場所を作成します。

.. code:: sql

   SELECT pgfs.create_storage_location(
       name => local_tmp_pgfs,
       uri  => file:///tmp/pgfs/
   );

S3、GCS、およびAzureのストレージ場所オプションの詳細については、
:ref:`PGFS documentation </pg_extensions/pgfs/>` を参照してください。

ステップ2ボリュームを作成する
-----------------------------

``aidb.create_volume()``
を使用して、PGFS格納場所をAIDBに接続します。ボリュームは、パイプラインとSQLファンクションが参照するものです。

.. code:: sql

   SELECT aidb.create_volume(
       name             => my_volume,
       server => my_s3_location,
       path         => /,
       data_format      => Text
       );

パラメーター

.. csv-table::
  :header: Parameter,Description
  :widths: 10,30
  :align: left
  :class: longtable

  `name`,ボリュームの一意の名前。パイプラインで参照するために使用されます。
  `storage_location`,アタッチするPGFSストレージ場所の名前。
  `sub_path`,格納場所内のオプションのパス。同じバケット内の異なるフォルダーを複数のボリュームでポイントする場合に役立ちます。
  `data_format`,このボリュームのデータの種類。 `Text`、`Image`、または`Pdf`のいずれか。パイプラインはこれを使用して、正しい解析ステップを選択します。

!!!注 ``data_format``
はメタデータです。オブジェクトを処理する方法をAIDBに指示しますが、フィルタリングはしません。ボリュームには、宣言されたフォーマットのオブジェクトのみが含まれていることを確認します。

例S3のPDF
^^^^^^^^^

.. code:: sql

   SELECT pgfs.create_storage_location(
       pdf_bucket,
       s3://my-docs-bucket,
       options => {"region": "us-east-1", "access_key_id": "<key>", "secret_access_key": "<secret>"}
   );

   SELECT aidb.create_volume(pdf_volume, pdf_bucket, /, Pdf);

例ローカルディレクトリ内の画像
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: sql

   SELECT pgfs.create_storage_location(local_tmp_pgfs, file:///tmp/pgfs/);

   SELECT aidb.create_volume(ocr_input_volume, local_tmp_pgfs, ocr_input/, Image);

ステップ3ボリュームをパイプラインソースとして使用する
-----------------------------------------------------

``aidb.create_pipeline()`` の\ ``source``
パラメーターをボリューム名に設定します。ボリュームソースは、パイプラインの観点からテーブルソースと同じように動作します。

.. code:: sql

   SELECT aidb.create_pipeline(
       name       => my_pdf_pipeline,
       source     => pdf_volume,
       step_1     => ParsePdf,
       step_2     => ChunkText,
       step_3     => KnowledgeBase,
       step_3_options => aidb.knowledge_base_config(bert_local, Text)
   );

完全なウォークスルーについては、 :ref:`Create a pipeline <Creating pipelines>` を参照してください。

ボリュームの管理
----------------

リストと削除
^^^^^^^^^^^^

すべてのボリュームをリストします。

.. code:: sql

   SELECT aidb.list_volumes();

ボリュームを削除します。

.. code:: sql

   SELECT aidb.delete_volume(my_volume);

!!!注
PGFSストレージ場所を削除すると、その上に作成されたすべてのボリュームも削除されます。

ボリュームの内容を検査する
^^^^^^^^^^^^^^^^^^^^^^^^^^

ボリュームをパイプラインに接続する前に、次の機能を使用して検証します。

.. code:: sql

   - - List all objects in the volume
   SELECT * FROM aidb.list_volume_content(my_volume);

   - - Read a specific file as BYTEA
   SELECT aidb.read_volume_file(my_volume, report.pdf);

   - - Read a plain text file as text
   SELECT convert_from(
       aidb.read_volume_file(my_volume, notes.txt),
       utf8
   );

これらの直接アクセス機能は、パイプラインから独立して、外部ストレージに対するカスタムSQLクエリーを構築するのにも役立ちます。