Amazon KendraにおけるWebクローラーコネクタの有用な機能とその設定方法（追記：Amazon Q For Business UseにおけるWebクローラーについて）

この記事は[セゾン情報システムズ Advent Calendar 2023](https://qiita.com/advent-calendar/2023/sisco)8日目の記事です。

# はじめに
**Amazon Kendra** とはエンタープライズサーチの機能を有したAWSのサービスです。
Amazon Kendraはインデックスに同期した全てのドキュメントを一括で検索してくれる全文検索と、質問の意図を理解しそれに近い意味のドキュメントを検索してくれるセマンティック検索という機能を有しているため、RAG（Retrieval Argumented Genaration、検索拡張性）においての検索エンジンとして注目されています。

https://aws.amazon.com/jp/kendra/

https://www.ibm.com/blogs/solutions/jp-ja/retrieval-augmented-generation-rag/

## この記事の使い方
Amazon Kendraは多数のデータソースコネクタを利用することができ、その中でも **Webクローラー** というコネクタが提供されています。

Webクローラーコネクタを利用すれば、社内のナレッジポータルなどの情報に対しKendraの検索機能を使うことができます。

今回は、上記のようなユースケースにおいて、Kendraの機能を十分に活用するために、Webクローラーコネクタの有用な機能やその設定方法をまとめました。

サービスを利用する際の参考にしてもらえると幸いです。

:::note info
ちなみにAmazon KendraのWebクローラにはv1.0とv2.0が存在し、主な違いはこちらです。
| 機能 | v1.0 | v2.0 |
| ---- | :--: | :--: |
| Webプロキシのサポート | ✓ | ✓ |
| 正規表現を用いたURLフィルタリング | ✓ | ✓ |
| フィールドマッピング | - | ✓ |
| VPC設定 | - | ✓ |
| 増分同期か全同期かの同期オプション | - | ✓ |

基本的には、より多くの機能を有したv2.0の利用が推奨されます。
よって以下ではAmazon kendraにおけるWebクローラーではv2.0のみ説明を行います。
:::

:::note warn
Webクローラーを実施する際は、[公式ドキュメントに記載](https://docs.aws.amazon.com/kendra/latest/dg/data-source-web-crawler.html)のあるよう、必ず自身で管理しているサイトもしくは許可を得たサイト以外で実施してください。
:::

# 事前準備
Amazon Kendraにおけるインデックスをまだ作成済みでない場合は作成してください。

その後ナビゲーションペインのData sources→Add data sourceよりWeb Crawler v2.0を選択してください。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/9f6b18f6-db94-9f76-cb3d-497e8798cacd.png)

# 設定方法

:::note warn
データソース名やIAMロールの設定、言語設定など、細かい説明が不要そうな設定は省いています。
:::
## ソースURL設定
クローリングを行う対象ソースURLの設定を4種類から設定できます。
![Amazon Kendra](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/6a9b41ff-c8d2-558e-8ff6-f07dc11723c3.png)

それぞれの機能は以下の通りです。
### Source URLs
コンソール画面のフォームに直接URLを入力します。
最大10URLまで設定可能です。

:::note info
AWS CLIを利用すると、最大100URLまで直接URLが設定可能です。
:::
### Source URLs files
URLがリストされたテキストファイルをS3バケットに配置し、URLをテキストファイルをS3に配置し、そのS3オブジェクトを指定します。
最大100URLまで設定することが可能です。
ファイルに記入のURLはそれぞれ下記のように改行させておく必要があります。

:::note info
テキストファイルにおける改行コードはCRLF、LFどちらでも同期は成功しました。
:::
```
https://example-url-1.com
https://example-url-2.com
https://example-url-3.com
・
・
・
```
### Source sitemaps
対象のWebサイトに設定してある下記のようなサイトマップURLを最大3URLまで設定できます。
```
https://www.example.com/sitemap.xml
```
### Source sitemap URLs file
下記のようなサイトマップファイルをS3に配置し、それをソースとして指定します。
最大3ファイルが入力可能で、その場合はzipに圧縮して1つのファイルにする必要があります。
```
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://www.example.com/</loc>
    <lastmod>2023-01-01</lastmod>
    <changefreq>monthly</changefreq>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://www.example.com/products</loc>
    <lastmod>2023-01-15</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://www.example.com/services</loc>
    <lastmod>2023-01-10</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://www.example.com/contact</loc>
    <lastmod>2023-01-01</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.5</priority>
  </url>
</urlset>
```

## 認証
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/f04f71b0-f4b1-55d4-afea-d854f69040bf.png )
認証情報を保存したAWS Secret Managerのシークレットを参照することで、認証が必要なWebサイトにアクセスすることができます。
また、Creat and new secretを選択することで、AWS Secret Manager シークレットを作成することが可能です。

:::note warn
認証情報を設定したをデータソース作成後、後からURLを変更する場合は、新しくデータソースを作成する必要があります。
:::

:::note warn
ソースがサイトマップファイルの場合、認証情報を使用することが出来ません。
:::

以下に認証機能と、シークレット作成方法を説明します。

### Basic認証およびNTLM/Kerberos認証の場合
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/101dfa4f-1ff2-30bf-1a1c-8eeacc2c65a7.png)
上記にシークレット名、ユーザ名、パスワードを入力することでBasic認証およびNTLM/Kerberos認証で使用するAWS Secret Managerシークレットを作成することができます。
### フォーム認証およびSAML認証の場合
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/e3b9b81c-2e55-cb54-53fa-dfd961c706fa.png)
上記にシークレット名、ログインページのURL、ユーザ名、パスワードに加え、それぞれのフィールドとボタンのXpathを入力することで、フォーム認証およびSAML認証で使用するAWS Secret Managerシークレットを作成することができます。
SAML認証の場合ユーザ名ボタンとパスワードボタンのXpathが必要ですが、フォーム認証の場合パスワードボタンのXpathのみです。

Xpath取得方法は下記ページを参考にしてください。

https://dietwork.net/winactor-xpath/

## Webプロキシ
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/1609e51e-2c74-f95f-8b5d-6fae901d32d7.png)
インターネット公開されていないの内部のWebサイトに接続する場合、使用したいプロキシサーバーのホスト名とポート番号を入力することで、内部のWebサイトに接続し、インデックスに同期することが可能です。
例えば、https://a.example.com/page1.html のホスト名は「a.example.com」で、ポート番号はHTTPSなので443です。
Webプロキシの資格情報が必要な場合は、AWS Secrets Managerシークレットを作成し、資格情報を保存することが可能です。

## VPC
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/42569258-fbad-5766-d407-a9127bd4a2d9.png)
VPCを選択することで、自身で管理しているVPCの中でWebクローラーを動作させることができます。
こちらも社内ネットーワークからでしか接続できないWebサイトに対するアクセスが用途として考えられます。
VPCを選択する場合、サブネットとセキュリティグループを選択する必要があります。

https://docs.aws.amazon.com/kendra/latest/dg/vpc-configuration.html

## 同期範囲（Sync scope）

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/1666ca33-8826-530b-e19b-2f9c5e69780d.png)

### 同期ドメイン範囲（Sync domain range）
#### Sync domains only
設定したURLにおいて、そのサイトのドメインのみをクロールする場合はこちらを選択します。
#### Sync domains with subdomains only
そのサイトのドメインと、サブドメインをクロールする場合はこちらを選択します。
#### Sync everything
そのサイトのドメイン、サブドメインと、さらにWeb ページがリンクしている他のドメインもクロールする場合はこちらを選択します。

   
### クロール深さ（crawl depth）
クロール深さを0~10の値で設定することができます。
 例えば深さレベル0を設定した場合。設定したソースURLのページがそのままコンテンツとしてインデックスに同期されます。
 レベル1に設定した場合、上記ページのリンクを押した先までが同期されます。
 レベル2を設定した場合、レベル1までのコンテンツと、さらにそのページのリンク先のコンテンツまでがインデックスに同期されます。
 
:::note warn
サイトの構成にもよりますが、深さレベルを大きくするほど同期に時間がかかるようになるため、注意が必要です。
:::


### 最大ファイルサイズ（Maximum file size）
  クロールするWebサイトまたは、添付ファイルの最大ファイルサイズを設定できます。

### 1ページ当たりの最大リンク数（Maximum links per page）
   クロールする1つのwebページに対して最大何リンクまでクロールするか設定できます。

### 最大スロットリング（Maximum throttling）
   1分間にクロールされるURLの最大数を設定できます。これによりWebサイトに対する負荷を調整できます。

### ウェブページにリンクしている添付ファイル（Include files that web pages link to）
   Webページにリンクしている添付ファイルをクロールするのかどうかを選択します。

### クロールパターン（Crawl URL Patterns）
Webクローラーがクロールを行うページもしくはクロールから除外するページのURLを正規表現で最大100パターンまで設定できます。

### インデックス登録URLパターン（URL Pattern to Index）
クロールしたコンテンツのうち、インデックスに同期を行うページもしくは除外するページのURLを正規表現で最大100パターンまで設定することが可能です。

## 同期モード(Sync mode)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/f6fcaab1-438a-9703-4955-b4ca06cd4588.png)
### New, modified, or deleted content sync
新規、変更済み、または削除済のコンテンツのみを同期する増分同期を行うことができます。
### Full Sync
以前のステータスに関係なく、すべてのコンテンツを同期します。
## フィールドマッピング（field mappings）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/c1aaf3c8-6397-9e45-b7e0-807bb66d2fb9.png)
同期したコンテンツの属性を、インデックスのフィールドにマッピングすることができます。これにより、特定の属性や文字列でフィルタリングしたり、ファセット検索することができます。
こちらのWebクローラーの場合、デフォルトでWeb page、_language_code、datasource_id、_s3_uriなどのフィールドにマッピングされます。

さらに、Webクローラーで同期されたコンテンツについては、HTMLの<meta>タグ内の情報をフィールドとして追加することができます。例えば、同期するWebページのソースコードに以下のような<meta>タグが含まれている場合、
```
 <meta name="keywords" content="サンプル">
```
以下の手順で、「keywords」のメタタグフィールドを追加できます。同期されたコンテンツについては、「サンプル」という情報が任意のフィールドに追加され、フィルタリングなどが可能になります。
1. 画面の「Add field」ボタンをクリック
2. meta tag field name「keywords」を入力して、任意のフィールドを追加

また、KendraのCustom document enrichment機能を使うことでドキュメントの属性を任意に作成、変更、削除することもできます。

https://docs.aws.amazon.com/ja_jp/kendra/latest/dg/custom-document-enrichment.html

# 追記：Amazon Q For Business Useについて

**Amazon Q For Business Use** とは、re:Invent 2023 Keynoteにおいて発表されたエンタープライズ支援向け生成AIサービスであるAmazon Qのうち、業務支援に特化したサービスです。
社内システムにおけるデータと情報に基づいて、質問に答え、概要を提供し、コンテンツを生成し、タスクを完了することができるという会話型インターフェースとなっています。

https://aws.amazon.com/jp/q/business-expert/

## Amazon Q For Business UseにおけるWebクローラー
以下はAmazon Q For Business Useにおけるコンソールの設定画面ですが、設定項目はほぼAmazon Kendraと共通であることが分かります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2988434/1bb16d66-b536-f856-2541-7aa656e26bb7.png)

https://docs.aws.amazon.com/ja_jp/amazonq/latest/business-use-dg/connector-webcrawler.html

Amazon Q For Business UseにおいてWebクローラーを設定する際にも、こちらの記事も参考にしていただけると幸いです。

:::note warn
Amazon Q For Business Useは2023/12/05時点では日本語未対応です。
:::

## 参考文献

https://docs.aws.amazon.com/ja_jp/kendra/latest/dg/data-source-web-crawler.html

https://docs.aws.amazon.com/ja_jp/amazonq/latest/business-use-dg/connector-webcrawler.html