@orizm/cli 3.3.0-beta.0 → 3.3.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/main.cjs +1 -1
- package/dist/cli/main.mjs +1 -1
- package/dist/docs/features/cms-sdk/install.md +1 -1
- package/dist/docs/features/consumer-sdk/install.md +1 -1
- package/dist/docs/features/dictionary.md +10 -7
- package/dist/docs/features/full-text-search/local-development.md +145 -0
- package/dist/docs/features/full-text-search.md +101 -5
- package/dist/docs/features/schema/database.md +9 -8
- package/dist/docs/index.md +2 -1
- package/dist/docs/manifest.json +3 -3
- package/package.json +2 -2
package/dist/cli/main.cjs
CHANGED
package/dist/cli/main.mjs
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# CMS SDKのインストール
|
|
4
4
|
|
|
5
5
|
> [!NOTE]
|
|
6
|
-
> このドキュメントは `@orizm/cms-sdk` の **v2.6.0-beta.
|
|
6
|
+
> このドキュメントは `@orizm/cms-sdk` の **v2.6.0-beta.1**
|
|
7
7
|
> に対応しています。プロジェクトにインストールされているバージョンが異なる場合、記載内容と実際の挙動が一致しないことがあります。
|
|
8
8
|
|
|
9
9
|
CMS SDKは、OrizmのCMS機能をWebサイトに組み込むためのJavaScriptライブラリです。このガイドでは、インストール手順とクライアントセットアップの方法を説明します。
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# Consumer SDKのインストール
|
|
4
4
|
|
|
5
5
|
> [!NOTE]
|
|
6
|
-
> このドキュメントは `@orizm/consumer-sdk` の **v2.6.0-beta.
|
|
6
|
+
> このドキュメントは `@orizm/consumer-sdk` の **v2.6.0-beta.1**
|
|
7
7
|
> に対応しています。プロジェクトにインストールされているバージョンが異なる場合、記載内容と実際の挙動が一致しないことがあります。
|
|
8
8
|
|
|
9
9
|
Consumer SDKはOrizmのデータにアクセスするためのJavaScriptライブラリです。WebサイトやアプリケーションからOrizmのコンテンツを取得する際に使用します。
|
|
@@ -35,16 +35,19 @@
|
|
|
35
35
|
|
|
36
36
|
## 前提
|
|
37
37
|
|
|
38
|
-
検索辞書そのものはプロジェクト単位の語彙で、辞書を登録するためのテーブルごとの設定はありません。ただし辞書が効くのは `semantic` / `hybrid` で検索できるテーブルに対してだけです。`orizm.config.ts` にプロジェクトの `semanticSearch` を宣言し、検索したいテーブルに `enableSearch: true` を付けて `orizm schema push`
|
|
38
|
+
検索辞書そのものはプロジェクト単位の語彙で、辞書を登録するためのテーブルごとの設定はありません。ただし辞書が効くのは `semantic` / `hybrid` で検索できるテーブルに対してだけです。`orizm.config.ts` にプロジェクトの `semanticSearch` を宣言し、検索したいテーブルに `enableSearch: true` を付け、意味検索の対象にする string 列に `semanticSearch: true` を付けて `orizm schema push` してください（[対象の列を指定する](./full-text-search.md#対象の列を指定するsemanticsearch-true)）。
|
|
39
39
|
|
|
40
|
-
```ts copy filename="orizm.config.ts" showLineNumbers {4,8}
|
|
40
|
+
```ts copy filename="orizm.config.ts" showLineNumbers {4,8,9,11}
|
|
41
41
|
import { defineConfig } from "@orizm/cli/config";
|
|
42
42
|
|
|
43
43
|
export default defineConfig({
|
|
44
44
|
semanticSearch: { enabled: true },
|
|
45
45
|
tables: {
|
|
46
46
|
blog: {
|
|
47
|
-
columns: {
|
|
47
|
+
columns: {
|
|
48
|
+
title: { type: "string", required: true, semanticSearch: true },
|
|
49
|
+
body: { type: "string", required: true, semanticSearch: true },
|
|
50
|
+
},
|
|
48
51
|
enableSearch: true,
|
|
49
52
|
},
|
|
50
53
|
},
|
|
@@ -90,7 +93,7 @@ export default defineConfig({
|
|
|
90
93
|
|
|
91
94
|
### 用語解説を検索結果に返す
|
|
92
95
|
|
|
93
|
-
説明（`description`）を付けたエントリは、それ自体が検索対象になります。CMS SDK で `semantic` または `hybrid` の検索をすると、検索結果に `_dictionary` が付き、クエリに近いものから最大 3
|
|
96
|
+
説明（`description`）を付けたエントリは、それ自体が検索対象になります。CMS SDK で `semantic` または `hybrid` の検索をすると、検索結果に `_dictionary` が付き、クエリに近いものから最大 3 件の用語解説が返ります。クエリと関連の薄いエントリは含まれないので、辞書のエントリが少なくても無関係な用語解説が並ぶことはありません。
|
|
94
97
|
|
|
95
98
|
```ts copy
|
|
96
99
|
const result = await cmsClient.tables.blog.search({
|
|
@@ -119,14 +122,14 @@ console.log(result._dictionary); // 辞書のヒット（最大 3 件）
|
|
|
119
122
|
|
|
120
123
|
`_dictionary` は状態によって 3 通りになります。
|
|
121
124
|
|
|
122
|
-
- **キーが無い**: `keyword` 検索、キーワード検索への劣化時、有効な説明付きのエントリが 1
|
|
125
|
+
- **キーが無い**: `keyword` 検索、キーワード検索への劣化時、有効な説明付きのエントリが 1 つも無いプロジェクト（反映待ちの間を含む）、辞書の検索が一時的に失敗したとき、どのテーブルも読めないキーでの検索
|
|
123
126
|
- **空配列**: 辞書は引けたが返せるエントリが無かった（通常は起きません）
|
|
124
127
|
- **配列**: ヒットあり
|
|
125
128
|
|
|
126
129
|
キーの有無は設定だけで決まるものではないため、`_dictionary` は常に省略され得るものとして扱ってください。
|
|
127
130
|
|
|
128
131
|
> [!WARNING]
|
|
129
|
-
>
|
|
132
|
+
> 辞書のヒットにはグループによる権限のフィルタが掛かりません（付くかどうかは、プロジェクト内のいずれかのテーブルを読めるキーかどうかだけで決まります）。特定のグループにだけ見せたい情報は説明に書かないでください。
|
|
130
133
|
>
|
|
131
134
|
> Consumer SDK の検索には `_dictionary`
|
|
132
135
|
> は付きません。辞書エントリには公開・下書きの区別が無いためです。
|
|
@@ -153,7 +156,7 @@ console.log(result._dictionary); // 辞書のヒット（最大 3 件）
|
|
|
153
156
|
|
|
154
157
|
CMS SDK の `cmsClient.dictionary` から操作します。テーブルの配下ではなくクライアント直下にあります。
|
|
155
158
|
|
|
156
|
-
辞書の登録・更新・削除には、プロジェクト内のいずれかのテーブルへの書き込み権限が必要です（[権限](./schema/authority.md) でどのテーブルにも書けないロールでは 403
|
|
159
|
+
辞書の登録・更新・削除には、プロジェクト内のいずれかのテーブルへの書き込み権限が必要です（[権限](./schema/authority.md) でどのテーブルにも書けないロールでは 403 になります）。一覧・取得には、プロジェクト内のいずれかのテーブルへの読み取り権限が必要です（どのテーブルも読めないロールでは 403 になります）。
|
|
157
160
|
|
|
158
161
|
### エントリの登録
|
|
159
162
|
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
<!-- source: docs/src/app/features/full-text-search/local-development/page.mdx -->
|
|
2
|
+
|
|
3
|
+
# セマンティック検索をローカルで動かす
|
|
4
|
+
|
|
5
|
+
Orizm をローカルで動かして開発するときに、[セマンティック検索](../full-text-search.md#検索モードセマンティック検索)（`mode: "semantic"` / `"hybrid"`）と [検索辞書](../dictionary.md) を手元で試す手順です。外部サービスは使わず、`docker compose` の OpenSearch だけで動きます。
|
|
6
|
+
|
|
7
|
+
> [!NOTE]
|
|
8
|
+
> この記事は Orizm 本体をローカルで起動する人（セルフホストや Orizm
|
|
9
|
+
> 自体の開発）向けです。マネージドの
|
|
10
|
+
> Orizm（app.orizm.com）を使っている場合、この手順は不要で、[プロジェクトの有効化](../full-text-search.md#検索モードセマンティック検索)だけで利用できます。
|
|
11
|
+
|
|
12
|
+
## 前提
|
|
13
|
+
|
|
14
|
+
Orizm 本体の開発環境が、リポジトリの README のセットアップ手順どおりに動いていることが前提です。具体的には `pnpm install`、`pnpm run generate`（Prisma クライアントなどの生成コード）、`pnpm run build --filter='./packages/*'`（ワークスペース内パッケージのビルド。`pnpm run dev` を一度起動していれば作られています）が済んでいて、DB を初期化し、開発者コンソールにログインできる状態です。以降の手順はその環境にセマンティック検索を足すものです。clone 直後の状態で手順 3 を実行すると、生成コードやパッケージのビルド成果物が無いためモジュールが見つからないエラーで止まります。また、パッケージをビルドしたあとに `pnpm install` を一度実行し直さないと `orizm` コマンドがリンクされず、手順 5 の push が `orizm: command not found` になります。
|
|
15
|
+
|
|
16
|
+
## 仕組み
|
|
17
|
+
|
|
18
|
+
既定の `ORIZM_EMBEDDING_SEARCH=off` では、検索は `keyword`（全文検索）だけが動き、ベクトルインデックスは作られません。`local` にすると、埋め込みの推論を OpenSearch クラスタ内のローカルモデル（多言語 MiniLM・384 次元）で行います。`docker compose` の OpenSearch は公式イメージがベースで、必要なプラグイン（ml-commons / k-NN / neural-search）は同梱されているため、追加のコンテナは要りません。
|
|
19
|
+
|
|
20
|
+
本番方針の Amazon Bedrock（`bedrock`）はローカルから到達できないので、本番と同じ経路での確認はステージング以降で行います。
|
|
21
|
+
|
|
22
|
+
## 手順
|
|
23
|
+
|
|
24
|
+
### 1. 推論経路を `local` にする
|
|
25
|
+
|
|
26
|
+
`apps/server/.env` に以下を設定します。
|
|
27
|
+
|
|
28
|
+
```bash filename="apps/server/.env"
|
|
29
|
+
ORIZM_EMBEDDING_SEARCH=local
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
> [!WARNING]
|
|
33
|
+
> 同じキーを `.env` の中に 2 回書かないでください。dotenv
|
|
34
|
+
> は後に書いた値が勝つため、重複していると意図しない値が黙って効きます。
|
|
35
|
+
|
|
36
|
+
### 2. OpenSearch を起動する
|
|
37
|
+
|
|
38
|
+
```bash copy
|
|
39
|
+
docker compose up
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### 3. 埋め込み基盤を用意する
|
|
43
|
+
|
|
44
|
+
DB のマイグレーションを当てたあと、埋め込みモデルの登録・配備と取り込みパイプラインの作成を行います。名前が似ていますが別のコマンドで、順番はこのとおりです。
|
|
45
|
+
|
|
46
|
+
```bash copy
|
|
47
|
+
pnpm run -F ./apps/server dev:migrate # DB のテーブル定義（Prisma）
|
|
48
|
+
pnpm run -F ./apps/server dev:migration # Content Plane と埋め込み基盤の同期
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
どちらも冪等で、再実行時は既存のものを再利用します。初回はモデルのダウンロードに数分かかります（待機の上限は 10 分）。ログに次の行が出れば完了です。
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
[semanticSearch] embedding infrastructure is ready
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### 4. サーバーとワーカーを起動する
|
|
58
|
+
|
|
59
|
+
```bash copy
|
|
60
|
+
pnpm run dev
|
|
61
|
+
pnpm dev:sandbox # 動作確認に sandbox を使う場合は別ターミナルで
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`pnpm run dev` には手順 3 の `dev:migration` は含まれません（本番でもマイグレーションはサーバーやワーカーとは別のタスクとして先に実行されます）。起動時のバナーの `EmbeddingSearch:` 行で、現在の推論経路を確認できます。
|
|
65
|
+
|
|
66
|
+
### 5. プロジェクトで有効にする
|
|
67
|
+
|
|
68
|
+
セマンティック検索は、システム側の設定（手順 1）とプロジェクト側の設定の両方が有効なときだけ動きます。`orizm.config.ts` に `semanticSearch` を宣言し、検索したいテーブルに `enableSearch: true` を付け、意味検索の対象にする string 列に `semanticSearch: true` を付けて push します（対象列の無いテーブルにはベクトルインデックスが作られず、`semantic` / `hybrid` は 403 になります。詳しくは [対象の列を指定する](../full-text-search.md#対象の列を指定するsemanticsearch-true)）。
|
|
69
|
+
|
|
70
|
+
```ts copy filename="orizm.config.ts" showLineNumbers {4,8,9,11}
|
|
71
|
+
import { defineConfig } from "@orizm/cli/config";
|
|
72
|
+
|
|
73
|
+
export default defineConfig({
|
|
74
|
+
semanticSearch: { enabled: true },
|
|
75
|
+
tables: {
|
|
76
|
+
article: {
|
|
77
|
+
columns: {
|
|
78
|
+
title: { type: "string", required: true, semanticSearch: true },
|
|
79
|
+
body: { type: "string", required: true, semanticSearch: true },
|
|
80
|
+
},
|
|
81
|
+
enableSearch: true,
|
|
82
|
+
},
|
|
83
|
+
},
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
同梱の sandbox-cms は宣言済みです。`orizm` CLI は `.env` を読まないので、開発者キーとプロジェクト名を環境変数で渡して push します（[認証](../cli/authentication.md)・[プロジェクトのリンク](../cli/project-linking.md)。`orizm auth login` と `orizm link` で済ませてもかまいません）。非対話シェルでは確認プロンプトを出せないので `--yes` を付けます。
|
|
88
|
+
|
|
89
|
+
```bash copy
|
|
90
|
+
ORIZM_API_KEY=<開発者キー> ORIZM_PROJECT=demo pnpm run -F ./apps/sandbox-cms orizm:push --yes
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
初期化スクリプトが作る demo プロジェクトの開発者キーは README の「Orizm Console」節にあります。環境変数なしで実行すると次のエラーで止まります。
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
Not authenticated. Run `orizm auth login`, or set ORIZM_API_KEY.
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
push すると `semanticSearch: true` の列を持つテーブルにベクトルインデックスが作られ、既存コンテンツの埋め込み（再構築）がワーカーで非同期に実行されます。
|
|
100
|
+
|
|
101
|
+
### 6. 動かして確かめる
|
|
102
|
+
|
|
103
|
+
- sandbox の検索画面で mode を切り替えて結果を見比べます。CMS SDK 経由は http://localhost:8000/admin/articles/search 、Consumer SDK 経由は http://localhost:8001/articles/search です
|
|
104
|
+
- 開発者コンソールのテーブル画面にある検索インデックスに `published_vector`（`enableDrafts` のテーブルでは `draft_vector` も）が出ていて、ドキュメント数が増えていれば埋め込みは作られています
|
|
105
|
+
- `semantic` / `hybrid` の結果の各行に `_semantic` が付いていれば、ベクトル検索が実際に動いています（付いていなければ、後述の劣化の状態です）
|
|
106
|
+
|
|
107
|
+
## 注意点
|
|
108
|
+
|
|
109
|
+
### 手順 3 を飛ばすと動かない
|
|
110
|
+
|
|
111
|
+
埋め込み基盤が無い状態でサーバーを起動すると、書き込み時のベクトル同期は失敗して再試行待ち（DLQ）に落ち、`semantic` / `hybrid` の検索は `search index is not ready` のエラー（403）で拒否されます。サーバーとワーカーは起動時に基盤を確認し、モデルが配備されていなければ次の error ログを出します。
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
[semanticSearch] ORIZM_EMBEDDING_SEARCH is set but no deployed embedding model was found
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
これが出たら手順 3 を実行してから起動し直してください。推論経路やモデルの設定を変えたときも同様です。
|
|
118
|
+
|
|
119
|
+
### 有効化の直後は 403 になる
|
|
120
|
+
|
|
121
|
+
プロジェクトを有効化した直後や、テーブルの列に `semanticSearch: true` を新しく付けた（または付け外しした）直後は、既存コンテンツ全件の埋め込みを作り直す再構築が走ります。完了するまで `semantic` / `hybrid` は 403 になり、完了すると使えるようになります。所要時間はコンテンツ量に比例します。`semanticSearch: true` の列が 1 つも無いテーブルはベクトルインデックス自体が作られず、`semantic` / `hybrid` は `search index not found (no column has semanticSearch: true)` の 403 になります。
|
|
122
|
+
|
|
123
|
+
### 本番とスコアは一致しない
|
|
124
|
+
|
|
125
|
+
ローカル（MiniLM・384 次元）と本番（Bedrock・Titan・1024 次元）では埋め込みモデルが違います。スコアの絶対値や順位、多言語の当たり方はローカルと本番で一致しません。検索の品質や、[検索辞書](../dictionary.md) の効き方の最終確認は、本番と同じ推論経路のステージング環境で行ってください。
|
|
126
|
+
|
|
127
|
+
### 埋め込み基盤が応答しないと `keyword` に劣化する
|
|
128
|
+
|
|
129
|
+
ベクトルインデックスができたあとで埋め込みの推論が失敗・タイムアウトすると、検索は失敗せずに `keyword` の結果に劣化して 200 を返します。このとき各行の `_semantic` と `_dictionary` は付きません。ローカルで「セマンティック検索が効いていない」と感じたら、まず `_semantic` の有無と OpenSearch のログを確認してください。
|
|
130
|
+
|
|
131
|
+
### OpenSearch のメモリ
|
|
132
|
+
|
|
133
|
+
モデルの推論も OpenSearch のコンテナ内で行うため、メモリが足りないと OpenSearch が落ちたり推論がタイムアウトしたりします。`compose.yaml` の既定は JVM ヒープ 512MB（`OPENSEARCH_JAVA_OPTS`）です。不安定な場合は Docker のメモリ割り当てと合わせて増やしてください。
|
|
134
|
+
|
|
135
|
+
### `off` に戻すのは非破壊
|
|
136
|
+
|
|
137
|
+
`ORIZM_EMBEDDING_SEARCH=off` に戻しても、既存のベクトルインデックスと埋め込み済みデータは残り、埋め込みの生成（書き込み時の同期と再構築）だけが止まります。この間の `semantic` / `hybrid` は `keyword` に劣化して応答します。`local` に戻してワーカーを起動すると、止まっていた間に古くなったインデックスは起動時の突き合わせで自動的に再構築されます。
|
|
138
|
+
|
|
139
|
+
### 古いモデルは自動では消えない
|
|
140
|
+
|
|
141
|
+
モデルや次元の設定を変えると、新しい名前のモデルが登録され、古いモデルは OpenSearch に残ります。ml-commons の API（`POST /_plugins/_ml/models/_search`）で登録済みのモデルを確認し、不要になったものは undeploy してから削除してください。
|
|
142
|
+
|
|
143
|
+
### 突き合わせだけをやり直す
|
|
144
|
+
|
|
145
|
+
ワーカーを再起動せず、定義も変えないまま、サーバー側の突き合わせ（ベクトルインデックスの再構築など）だけを再実行したいときは、`orizm schema push` に [`--force`](../cli/commands/schema.md#orizm-schema-push) を付けます。差分が無くても定義が送られ、突き合わせが走ります。
|
|
@@ -79,10 +79,38 @@ await cmsClient.tables.blog.search({ query: "経費の精算", mode: "hybrid" })
|
|
|
79
79
|
|
|
80
80
|
`semantic` / `hybrid` はプロジェクトでセマンティック検索が有効な場合のみ利用できます（無効なプロジェクトではエラーになります）。有効化は `orizm.config.ts` に `semanticSearch: { enabled: true }` を宣言して `orizm schema push` で反映します（無効に戻すときは `enabled: false` を明示します。宣言を省略した定義は現状維持です）。有効化の直後はベクトルインデックスの構築が完了するまで `semantic` / `hybrid` が 403 になります（構築が終わり次第利用できます）。`semantic` / `hybrid` で検索した場合は、検索結果の各行に `_semantic`（スコア・ヒットに寄与したチャンク・レーン別順位）が付与されます（`keyword` では付きません）。
|
|
81
81
|
|
|
82
|
+
### 対象の列を指定する（`semanticSearch: true`）
|
|
83
|
+
|
|
84
|
+
`semantic` / `hybrid` で検索できるのは、`semanticSearch: true` を付けた string 列を 1 つ以上持つテーブルだけです（付いていないテーブルは `enableSearch: true` があっても `keyword` のみで、`semantic` / `hybrid` は 403 `search index not found (no column has semanticSearch: true)` になります）。`semanticSearch: true` の列を持つテーブルには `enableSearch: true` が必要です（無いと push が失敗します）。`tableModules` 内の string 列にも付けられ、そのモジュールを使うテーブルの対象になります。
|
|
85
|
+
|
|
86
|
+
```ts copy filename="orizm.config.ts" showLineNumbers {6,10}
|
|
87
|
+
export default defineConfig({
|
|
88
|
+
semanticSearch: { enabled: true },
|
|
89
|
+
tables: {
|
|
90
|
+
blog: {
|
|
91
|
+
columns: {
|
|
92
|
+
title: { type: "string", required: true, semanticSearch: true },
|
|
93
|
+
body: { type: "string", required: true, semanticSearch: true },
|
|
94
|
+
slug: { type: "string", required: true }, // keyword 検索の対象にはなるが、埋め込みには載らない
|
|
95
|
+
},
|
|
96
|
+
enableSearch: true,
|
|
97
|
+
},
|
|
98
|
+
},
|
|
99
|
+
});
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
埋め込み（ベクトル）の元になる本文は、`semanticSearch: true` の列の値を定義順につないだテキストです。検索結果の `_semantic.chunks` に返るチャンクもこの本文を分割したもので、`keyword` の検索対象（全テキスト列）とは一致しません。埋め込みの費用はこの本文の量で決まるので、意味検索に要らない列（slug・型番の一覧・機械的なコード）には付けないでください。列の付け外しは、そのテーブルのベクトルインデックスの再構築を伴います（完了までは 403 になります。最後の `semanticSearch: true` を外すとベクトルインデックスは削除されます）。
|
|
103
|
+
|
|
104
|
+
> [!WARNING]
|
|
105
|
+
> 列を絞れば精度が上がる、というものではありません。意味検索は文脈の量で効きます。`title`
|
|
106
|
+
> だけを対象にすると十数文字の埋め込みになり、言い換えや課題表現との距離が出にくくなります。また列をまたぐ手掛かり（製品名は
|
|
107
|
+
> `title`、用途は
|
|
108
|
+
> `body`）も失われます。人が読んで内容を表す列（タイトル・本文・説明）はまとめて付け、識別子や機械的な値だけを外すのが目安です。
|
|
109
|
+
|
|
82
110
|
> [!WARNING]
|
|
83
111
|
> セマンティック検索を利用できるかどうかは、プロジェクトの設定に加えてシステム側の設定でも決まります。システム側で有効になっていない環境では、`semanticSearch: { enabled: true }` の push は成功しますが `semantic` / `hybrid` の検索は利用できません（ベクトルインデックスが作られていない場合は 403 になり、過去に作られたインデックスが残っている場合は `keyword` の結果に劣化します）。利用中の環境で使えるかは管理者に確認してください。
|
|
84
112
|
|
|
85
|
-
CMS SDK の `semantic` / `hybrid` では、プロジェクトの [検索辞書](./dictionary.md) に説明を付けた有効なエントリがあれば、検索結果に辞書のヒット（`_dictionary
|
|
113
|
+
CMS SDK の `semantic` / `hybrid` では、プロジェクトの [検索辞書](./dictionary.md) に説明を付けた有効なエントリがあれば、検索結果に辞書のヒット（`_dictionary`）も付与されます（説明付きのエントリが無いプロジェクトではキー自体が付きません。また [権限](./schema/authority.md) でどのテーブルも読めないキーの検索にも付きません）。検索辞書に同義語を登録しておくと、`hybrid` の検索クエリに表記の言い換えが足され、社内の俗称や型番の表記ゆれでも目的のコンテンツに当たるようになります。
|
|
86
114
|
|
|
87
115
|
フォーム投稿（submissions）の検索は `keyword` のみ対応です（`semantic` / `hybrid` を指定すると 403 になります）。
|
|
88
116
|
|
|
@@ -96,14 +124,16 @@ CMS SDK の `semantic` / `hybrid` では、プロジェクトの [検索辞書](
|
|
|
96
124
|
|
|
97
125
|
`semantic` / `hybrid` の上限が小さいのは、`semantic` では近傍探索（ANN）の候補プールが深い窓を安定して裏付けられない（加えて窓の各行にチャンク本文を付けて返す）ため、`hybrid` では融合（RRF）が固定ランク窓の中でだけページ間の順序を安定して定義できるためです。深いページングや件数だけの取得が必要な場合は `keyword` を使ってください。`limit` / `offset` は mode を問わず整数かつ 0 以上のみ受け付けます。
|
|
98
126
|
|
|
99
|
-
`query` は
|
|
127
|
+
`query` は `semantic` / `hybrid` では 512 文字までです（超過は 400 になります）。`keyword` には文字数の上限がありません。空文字や空白だけの `query` は mode を問わず検索せず、0 件（`contents: []`, `totalCount: 0`）を返します。
|
|
100
128
|
|
|
101
129
|
> [!WARNING]
|
|
102
130
|
> `semantic` / `hybrid` の `totalCount`
|
|
103
131
|
> は正確な件数ではなく、**ページ数の計算には使えません**。 `semantic` の
|
|
104
|
-
> `totalCount`
|
|
105
|
-
>
|
|
106
|
-
>
|
|
132
|
+
> `totalCount`
|
|
133
|
+
> は近傍探索（ANN）の候補プールに入ったコンテンツ数です。候補プールの大きさは固定なのでページを進めても値は変わりませんが、`offset
|
|
134
|
+
> + limit`
|
|
135
|
+
> の上限（100）を超える値になることがあり、該当するコンテンツが無いクエリでも 0
|
|
136
|
+
> にはなりません（ANN は常に最も近いものを返すため）。`hybrid` の `totalCount`
|
|
107
137
|
> は下界（2 レーンの大きい方。返した行数を下回ることはありません）です。`limit:
|
|
108
138
|
> 0` が `keyword` 専用なのも同じ理由です。正確な件数やページ数が必要な場合は
|
|
109
139
|
> `keyword` を使ってください。
|
|
@@ -112,3 +142,69 @@ CMS SDK の `semantic` / `hybrid` では、プロジェクトの [検索辞書](
|
|
|
112
142
|
> 埋め込み基盤の一時的な障害時は、検索を失敗させる代わりに `keyword`
|
|
113
143
|
> の結果に劣化して応答します（このとき `_semantic` と `_dictionary`
|
|
114
144
|
> は付かず、`hybrid` で効いていた検索辞書によるクエリの言い換えも外れます）。
|
|
145
|
+
|
|
146
|
+
### 検索結果の `_semantic`
|
|
147
|
+
|
|
148
|
+
`semantic` / `hybrid` で検索すると、`contents` の各行に `_semantic` が付きます。コンテンツは埋め込みを作る前に一定の長さの断片（チャンク）に分割され、検索はチャンク単位で近さを測ります。`chunks` にはその行でクエリに近かったチャンクが入るので、長い本文のどこが当たったのかを画面で示すのに使えます。
|
|
149
|
+
|
|
150
|
+
| フィールド | 説明 |
|
|
151
|
+
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
152
|
+
| `score` | 行のスコア。`semantic` ではベクトル検索（kNN）の近さ、`hybrid` では 2 つのレーンを融合した RRF の値です。尺度が違うため mode をまたいで比較できません |
|
|
153
|
+
| `chunks` | ヒットに寄与したチャンクの配列。各要素は `text`（チャンク本文）と `score`（チャンク単位の近さ）を持ちます |
|
|
154
|
+
| `keywordRank` | キーワード検索のレーンでの順位。`hybrid` でそのレーンにヒットした行にだけ付きます。ヒットしなかった行と `semantic` ではキー自体が省略されます |
|
|
155
|
+
| `vectorRank` | ベクトル検索のレーンでの順位。`semantic` では常に付き、`hybrid` でそのレーンにヒットしなかった行ではキー自体が省略されます |
|
|
156
|
+
|
|
157
|
+
```ts copy
|
|
158
|
+
const result = await cmsClient.tables.blog.search({
|
|
159
|
+
query: "寒さで壊れる",
|
|
160
|
+
mode: "hybrid",
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
for (const row of result.contents) {
|
|
164
|
+
console.log(row.title, row._semantic?.score, row._semantic?.chunks[0]?.text);
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`_semantic` は上で説明した劣化時には付きません。常に省略され得るものとして扱ってください。`hybrid` で `keywordRank` と `vectorRank` の両方が付いている行は、字面と意味の両方で当たった行です（`null` は入らないので、有無は `undefined` との比較で判定してください）。
|
|
169
|
+
|
|
170
|
+
## 検索への反映タイミング
|
|
171
|
+
|
|
172
|
+
コンテンツの作成・更新・削除は、保存が完了したあと非同期で検索インデックスに反映されます。所要時間の目安は以下のとおりです（Orizm のステージング環境での実測値。混雑時や埋め込み基盤の遅延時はこれより長くなります）。
|
|
173
|
+
|
|
174
|
+
| 操作 | 反映先 | 目安 |
|
|
175
|
+
| -------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------ |
|
|
176
|
+
| コンテンツの作成・更新 | `keyword` | 数秒（実測 1.5〜4 秒） |
|
|
177
|
+
| コンテンツの作成・更新（埋め込みの生成を含む） | `semantic` / `hybrid` | 数秒（実測 2 秒程度。本文を書き換えた再生成も同程度） |
|
|
178
|
+
| 公開 | Consumer SDK の検索（全 mode） | 数秒（実測 2 秒程度。公開したコンテンツはインデックスの同期を待ってから現れます） |
|
|
179
|
+
| 非公開・削除 | Consumer SDK の検索（全 mode） | 1 秒未満（結果の行は DB から引き直すため、公開ビューから消えた行は即座に消えます） |
|
|
180
|
+
| セマンティック検索の有効化・テーブルへの `semanticSearch: true` の新規付与 | `semantic` / `hybrid` | コンテンツ量に比例（既存コンテンツ全件の埋め込みを作り直します。実測 76 件で約 1 分） |
|
|
181
|
+
| `semanticSearch: true` の列（モジュール内を含む）の追加・削除・順序変更 | `semantic` / `hybrid` | コンテンツ量に比例（索引を作り直します。埋め込みを作り直すのは本文が変わったコンテンツだけです） |
|
|
182
|
+
|
|
183
|
+
CMS SDK の検索は下書きも対象にするため、コンテンツを非公開にしても CMS SDK の検索結果からは消えません。公開状態で結果を絞りたい場合は Consumer SDK の検索を使ってください。
|
|
184
|
+
|
|
185
|
+
有効化の直後や、テーブルの列に `semanticSearch: true` を初めて付けた直後は、既存コンテンツ全件の埋め込みを作り直す処理（再構築）がバックグラウンドで走ります。完了するまで `semantic` / `hybrid` は 403 になり、完了すると利用できます。再構築の進み具合は、開発者コンソールのテーブル画面にある検索インデックス（`published_vector`。`enableDrafts` のテーブルでは `draft_vector` も）のドキュメント数で確認できます。`enableDrafts` を付けたり外したりしたときも `draft_vector` の作成・削除が走り、付けた直後は `draft_vector` が出来上がるまで CMS SDK の `semantic` / `hybrid` は 403 になります。付けたときは、そのテーブルの既存コンテンツ全件の埋め込みを作り直します（埋め込みモデルの推論費用が掛かります）。
|
|
186
|
+
|
|
187
|
+
`semanticSearch: true` の列（モジュール内の列を含む）を追加・削除したり順序を変えたりしたときも、フラグの付いた列が 1 つ以上残っていれば、スキーマを push すると再構築が走ります。こちらは既存の索引で検索を受け続けながら裏で作り直し、完了した時点で切り替わります（403 にはなりません）。切り替わるまでは、外した列の本文が `_semantic.chunks` に残ることがあります。フラグの無い列（`json` や他の型の列を含む）は本文に含まれないため、追加・削除しても再構築は走りません。最後のフラグを外すとベクトルインデックスは削除され、`semantic` / `hybrid` は 403 になります。
|
|
188
|
+
|
|
189
|
+
[検索辞書](./dictionary.md) の反映タイミングは辞書の記事を参照してください（同義語による言い換えは即時、用語解説の検索対象化は非同期です）。
|
|
190
|
+
|
|
191
|
+
## セルフホスト環境での前提
|
|
192
|
+
|
|
193
|
+
Orizm をセルフホストしている場合、セマンティック検索を使うにはシステム側の準備が必要です。マネージドの Orizm（app.orizm.com）では不要で、プロジェクトの有効化だけで利用できます。
|
|
194
|
+
|
|
195
|
+
- **OpenSearch**: 2 系の公式ディストリビューションが必要です。ベクトル検索（k-NN）、埋め込みの推論（ml-commons）、ベクトル索引への取り込み（neural-search）の 3 つのプラグインを使いますが、いずれも公式ディストリビューションに同梱されています。日本語の全文検索には kuromoji と ICU の解析プラグインも必要です（Orizm 付属の docker compose 用イメージはこれらを追加したものです）
|
|
196
|
+
- **推論経路の設定**: サーバーとワーカーの環境変数 `ORIZM_EMBEDDING_SEARCH` で埋め込みの推論経路を選びます
|
|
197
|
+
|
|
198
|
+
| 値 | 動作 |
|
|
199
|
+
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
200
|
+
| `off`（既定） | セマンティック検索を無効にします。ベクトルインデックスは作られず、`semantic` / `hybrid` は利用できません |
|
|
201
|
+
| `local` | OpenSearch クラスタ内のローカルモデル（多言語 MiniLM・384 次元）で推論します。開発や小規模な検証向けで、外部サービスは不要です |
|
|
202
|
+
| `bedrock` | Amazon Bedrock の埋め込みモデル（既定 `amazon.titan-embed-text-v2:0`・1024 次元）に推論を外出しします。本番向けの方式です |
|
|
203
|
+
|
|
204
|
+
- **`bedrock` のときの追加設定**: `AWS_REGION`、`BEDROCK_EMBEDDING_MODEL`、`BEDROCK_EMBEDDING_DIMENSION` でモデルと次元を指定します。マネージドの OpenSearch（Amazon OpenSearch Service）では、Bedrock を呼び出すときに OpenSearch 側が引き受ける IAM ロールを `BEDROCK_CONNECTOR_ROLE_ARN` に指定します。未設定の場合は `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` が接続情報として使われます
|
|
205
|
+
- **埋め込み基盤の準備**: 埋め込みモデルの登録・配備と取り込みパイプラインの作成は、マイグレーションタスクが行います（冪等で、既にあれば再利用します）。サーバーとワーカーを起動する前にマイグレーションを実行してください。推論経路やモデルの設定を変えたときも同様です。準備ができていない状態でサーバーを起動すると、起動ログにモデルが見つからない旨の error が出て、`semantic` / `hybrid` は 403 になります
|
|
206
|
+
- **`off` は非破壊の停止スイッチ**: 一時的に `off` にしても既存のベクトルインデックスと埋め込み済みデータは残り、埋め込みの生成（書き込み時の同期と再構築）だけが止まります。この間の `semantic` / `hybrid` は `keyword` の結果に劣化して応答します。`local` / `bedrock` に戻してワーカーを起動すると、止まっていた間に古くなったインデックスは起動時の突き合わせで自動的に再構築されます
|
|
207
|
+
|
|
208
|
+
> [!WARNING]
|
|
209
|
+
> `local` と `bedrock`
|
|
210
|
+
> では埋め込みモデルも次元も違うため、スコアの値や順位は環境間で一致しません。品質の確認は本番と同じ推論経路で行ってください。推論経路やモデルを切り替えると、既存のベクトルインデックスはすべて作り直されます。
|
|
@@ -58,14 +58,15 @@ export default defineConfig({
|
|
|
58
58
|
|
|
59
59
|
以下のオプションが設定できます。
|
|
60
60
|
|
|
61
|
-
| オプション
|
|
62
|
-
|
|
|
63
|
-
| required
|
|
64
|
-
| readonly
|
|
65
|
-
| pattern
|
|
66
|
-
| minLength
|
|
67
|
-
| maxLength
|
|
68
|
-
| default
|
|
61
|
+
| オプション | 説明 | 型 | デフォルト |
|
|
62
|
+
| -------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------- |
|
|
63
|
+
| required | 必須項目であることを示します。 | boolean | false |
|
|
64
|
+
| readonly | 読み取り専用であることを示します。 | boolean | false |
|
|
65
|
+
| pattern | 正規表現を用いて文字列のパターンを指定します。 | string | - |
|
|
66
|
+
| minLength | 文字列の最小長を指定します。 | number | - |
|
|
67
|
+
| maxLength | 文字列の最大長を指定します。 | number | - |
|
|
68
|
+
| default | デフォルト値を指定します。 | string | - |
|
|
69
|
+
| semanticSearch | セマンティック検索の埋め込み対象にします。string 列のみ。テーブルに `enableSearch: true` が必要です（無いと push が失敗します）。 | boolean | false |
|
|
69
70
|
|
|
70
71
|
```ts copy
|
|
71
72
|
{
|
package/dist/docs/index.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Orizm docs (v3.3.0-beta.
|
|
1
|
+
# Orizm docs (v3.3.0-beta.1)
|
|
2
2
|
|
|
3
3
|
Bundled Orizm docs, version-matched to the installed `@orizm/cli`.
|
|
4
4
|
Read the relevant page before generating Orizm code. Files are relative to this directory.
|
|
@@ -60,6 +60,7 @@ Starter Kit v2: edit only `apps/cms`, `apps/consumer`, `packages/design-editor`.
|
|
|
60
60
|
- [フォームエディター](./features/form/editor.md)
|
|
61
61
|
- [受信データの管理](./features/form/submission.md)
|
|
62
62
|
- [全文検索](./features/full-text-search.md)
|
|
63
|
+
- [セマンティック検索をローカルで動かす](./features/full-text-search/local-development.md)
|
|
63
64
|
- [履歴管理](./features/history.md)
|
|
64
65
|
- [スキーマとは](./features/schema/about.md)
|
|
65
66
|
- [権限](./features/schema/authority.md)
|
package/dist/docs/manifest.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@orizm/cli",
|
|
3
|
-
"version": "3.3.0-beta.
|
|
3
|
+
"version": "3.3.0-beta.1",
|
|
4
4
|
"description": "Orizm CLI",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"open": "11.0.2",
|
|
37
37
|
"prettier": "3.9.6",
|
|
38
38
|
"valibot": "1.4.2",
|
|
39
|
-
"@orizm/common": "2.6.0-beta.
|
|
39
|
+
"@orizm/common": "2.6.0-beta.1"
|
|
40
40
|
},
|
|
41
41
|
"bin": {
|
|
42
42
|
"orizm": "dist/cli/main.mjs"
|