立てて、運用する

ochakai は、あなたの Google Cloud プロジェクトの中で動きます。中身は Cloud Run のサービス 1 つと、いちばん小さい Cloud SQL インスタンス 1 つです。

内容は v0.27.5 時点のものです。元にしているのは製品リポジトリの Cloud Run デプロイ手順書・Terraform モジュール・要件と設定・デプロイの運用で、細かい分岐はそれぞれの原文にあります。この次は「エージェントを繋ぐ」です。

0. 前提条件と、月にいくらか

本番で動かすとは、Google Cloud で動かすことです。到達は Cloud Run の IAM が、データベースの認証は Cloud SQL IAM が受け持ちます。この 2 つが揃っているため、ochakai は自前の秘密を 1 つも持ちません。外にも認証の経路は 1 つありますが(§4)、埋め込みは Vertex AI だけで、外での検索は字句検索になります(§5)。

deploy/compose.yaml は同じバイナリを認証オフでローカルに動かす、開発用のハーネスです。自分のデータで試すだけなら、これがいちばん速い経路です。

手元に要るものは、この 5 つです。

データベースは PostgreSQL 17 です。最初のマイグレーションが pg_trgm 拡張を作るため、それを作れる権限が一度だけ要ります(§1 の bootstrap)。セマンティック検索を使うなら vector(pgvector)も同じところで入り、Google Cloud 上では既定で有効になります。

費用は、us-central1 でのおおよその見積もりです。

料金のほとんどは Cloud SQL で、asia-northeast1 のようなアジアのリージョンはやや高くなります。この表はバックアップ無しの構成です。Terraform の既定は日次バックアップが on で、使い捨ての評価環境でなければ、そのままにしてください。

1. 立てる

経路は 2 つあって、できあがるものは同じです。推奨は Terraform で、1 回の terraform apply と手作業 1 つで済み、差分としてレビューでき、きれいに壊せます。gcloud は同じものを 1 つずつ手で作ります。

どちらの経路でも、作られるものはこの 5 つです。

経路 A: Terraform

git clone https://github.com/na0fu3y/ochakai && cd ochakai/deploy/terraform
cp terraform.tfvars.example terraform.tfvars   # project・region・invokers を書く
terraform init
terraform apply    # Cloud SQL の作成に 10〜15 分かかる

手作業はこの bootstrap 1 つだけです。拡張とオブジェクト権限は、マイグレーションが走る前に要ります。貼り付ける SQL は terraform output が出します。

gcloud sql users set-password postgres --instance=ochakai --prompt-for-password
cloud-sql-proxy "$(terraform output -raw sql_connection_name)" --port 55432 &
psql "host=localhost port=55432 dbname=ochakai user=postgres"
# psql の中で「terraform output -raw database_bootstrap_sql」の出力を実行したら完了

terraform output -raw use_command   # チームに配る ochakai use コマンドを表示

export PROJECT_ID=<your-project>
export REGION=asia-northeast1
gcloud config set project $PROJECT_ID
gcloud services enable run.googleapis.com sqladmin.googleapis.com \
  sql-component.googleapis.com artifactregistry.googleapis.com

# Cloud Run は ghcr.io から直接 pull できないので、プロキシするリポジトリを作る
gcloud artifacts repositories create ghcr \
  --repository-format=docker \
  --mode=remote-repository \
  --remote-docker-repo=https://ghcr.io \
  --location=$REGION
export VERSION=0.27.5
export IMAGE=$REGION-docker.pkg.dev/$PROJECT_ID/ghcr/na0fu3y/ochakai:$VERSION

# データベース(作成に 10〜15 分)
gcloud sql instances create ochakai \
  --database-version=POSTGRES_17 \
  --edition=enterprise \
  --tier=db-f1-micro \
  --region=$REGION \
  --storage-size=10 \
  --storage-type=SSD \
  --no-storage-auto-increase \
  --no-backup \
  --database-flags=cloudsql.iam_authentication=on
gcloud sql databases create ochakai --instance=ochakai
export DB_PASSWORD=$(openssl rand -hex 24)
gcloud sql users create ochakai --instance=ochakai --password=$DB_PASSWORD

# サービスアカウント。IAM データベース認証で DB に繋ぐ
gcloud iam service-accounts create ochakai-run --display-name="ochakai service"
export SERVICE_ACCOUNT=ochakai-run@$PROJECT_ID.iam.gserviceaccount.com
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/cloudsql.client
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/cloudsql.instanceUser
export DB_SA_USER=ochakai-run@$PROJECT_ID.iam
gcloud sql users create $DB_SA_USER --instance=ochakai --type=cloud_iam_service_account

cloud-sql-proxy $PROJECT_ID:$REGION:ochakai --port 55432 &
psql "host=localhost port=55432 dbname=ochakai user=ochakai"

CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS vector;
-- vector は §5 のセマンティック検索用。Cloud SQL の pgvector は
-- trusted extension ではないため、admin が作る

GRANT USAGE, CREATE ON SCHEMA public TO "ochakai-run@<PROJECT_ID>.iam";
GRANT ALL ON ALL TABLES IN SCHEMA public TO "ochakai-run@<PROJECT_ID>.iam";
GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO "ochakai-run@<PROJECT_ID>.iam";
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO "ochakai-run@<PROJECT_ID>.iam";
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO "ochakai-run@<PROJECT_ID>.iam";

# デプロイして、組織に invoke を許可する
gcloud run deploy ochakai \
  --image=$IMAGE \
  --region=$REGION \
  --service-account=$SERVICE_ACCOUNT \
  --no-allow-unauthenticated \
  --min-instances=0 --max-instances=1 \
  --cpu=1 --memory=512Mi \
  --add-cloudsql-instances=$PROJECT_ID:$REGION:ochakai \
  --set-env-vars="OCHAKAI_DB_IAM_AUTH=true" \
  --set-env-vars="OCHAKAI_DATABASE_URL=postgres:///ochakai?host=/cloudsql/$PROJECT_ID:$REGION:ochakai&user=$DB_SA_USER"
gcloud run services add-iam-policy-binding ochakai --region=$REGION \
  --member=domain:your-org.example --role=roles/run.invoker

# セマンティック検索(日本語のベースなら特に推奨。詳しくは §5)
gcloud services enable aiplatform.googleapis.com
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/aiplatform.user

export OCHAKAI_URL=$(gcloud run services describe ochakai --region=$REGION --format='value(status.url)')

allUsers を付けてはいけません。ochakai が読む identity のヘッダーは、Cloud Run の IAM チェックの背後にあってはじめて信用できます。例外は、identity を一切読まず何も書き込まない public(§4)だけです。

2. 動いていることを確かめる

サービスは公開呼び出しを受け付けないため、素の curl は IAM に阻まれます。手元から確かめるには proxy を通します。

gcloud run services proxy ochakai --region=$REGION --port=8787 &
curl http://localhost:8787/health

/healthz ではなく /health です。Google Frontend は run.app の URL 上で /healthz を横取りし、コンテナへ届く前に自前の 404 を返します。リクエストログにも残らないため、生きているサービスが死んで見えます。

/health は liveness だけを見ます。データベースまで含めて確かめるなら、store に触る読み取りを打ちます。GET /api/v1/search?sort=verified_at&limit=1 は、データベースが答えたときだけ成功します。CLI からは ochakai whoami が同じことをしつつ、サーバーがどの identity を見ているかも表示します。

ochakai use $OCHAKAI_URL
ochakai whoami

立ち上げで詰まる場所は、だいたい次の 4 つです。

クライアント側で詰まったとき(検索が空、import が飛ばされる、409 や 412、web UI が空)の見分け方は、トラブルシューティングにあります。

3. 環境変数

設定はすべて環境変数です。設定ファイルはありません。よく使うのは次の 8 つで、OCHAKAI_DATABASE_URL 以外はすべて省略できます。

この表に無い OCHAKAI_* を置くと、サーバーは起動しません。エラーはその名前を挙げ、ochakai が読む名前を並べます。Cloud Run では起動しないリビジョンにトラフィックが移らないため、直前のリビジョンが答え続けます。名前を消せば次のデプロイは通ります。

更新には --update-env-vars を使ってください。--set-env-vars はすべての環境変数を置き換えるため、OCHAKAI_DATABASE_URL を消してしまいます。

全変数と、それぞれの細かい挙動は要件と設定にあります。クライアント側のコマンドは OCHAKAI_URL を読み、ochakai use で選んだサーバーより優先します。

4. 誰が届くか

到達できるかどうかが、アクセスモデルのすべてです。デプロイに誰が届いてよいかは、Cloud Run の IAM が決めます。ochakai は転送されてきた呼び出し元の identity(人なら human:<email>、サービスアカウントなら process:<sa-email>)を読んで、来歴として記録します。既定では認可はありません。届いた人は全部を読み書きできます。

境界が要るなら

答えは 2 つです。

• デプロイを分ける。Cloud Run のサービスと、同じ Cloud SQL インスタンスの中の別データベースを足すだけで、到達とデータベースの二層で効きます。
• 同じバンドルの中で、ディレクトリ単位に権利を置く。v0.24.1 からの任意の機能で、ochakai access がポリシーを表示・置換します。付与を 1 つも書いていないデプロイの挙動は、前の段落のままです。

ポリシーは 1 つの文書で、丸ごと置き換わります。規則は一行につき、1 つの principal に、1 つのディレクトリ以下の権利を与えます。読めるのが既定で、may_write があれば書けます。v0.27.0 の may_admin は、そのディレクトリ以下の規則そのものを編集する権利で、チームにディレクトリごと預けるためのものです。渡した相手に見えるのはその prefix 以下の規則だけで、他のディレクトリの規則は相手の保存を跨いで残ります。

順番と競合に、罠が 1 つずつあります。

• 最初の一行を置けるのは管理者だけです。ポリシーが空のうちに OCHAKAI_ADMINS に居ない呼び出し元が書こうとすると 403 になり、何も書かれません。一行入った時点で、ポリシーは管理者のものになります。
• 二人で編集するなら、読んだ版を添えます。文書が丸ごと置き換わるため、二人が同じポリシーを読んで一行ずつ足すと、後に保存した側の行しか残りません。エラーは出ません。気づく契機は、消された側が「読めない」と言ってくることだけです。

ochakai access --json > policy.json
$EDITOR policy.json
ochakai access -f policy.json --if-match "$(jq -r .version policy.json)"

--if-match は、読んだときの版をポリシーがまだ持っているときにだけ置き換え、そうでなければ何も書かずに失敗します。一行足す自動化を書くなら、これは任意ではありません。空のポリシーにも版があります。

これはドキュメントごとの権限ではありません。読めるドキュメントの本文が隠したディレクトリの id を名指していれば、その id は読めます。バンドル全体への may_admin は置けません。バンドル全体を扱う操作(export の tar・reembed・ポリシー自身)は OCHAKAI_ADMINS のもので、stats と move は含みません。付与を持つ利用者も自分の数を読めます。move は v0.27.2 から外れました。動かすドキュメントと行き先、それを指している生きたドキュメントが自分の書ける場所に収まるなら、管理者は要りません。1 つでも外にあると、丸ごと断られます。

デプロイの姿勢

OCHAKAI_MODE の姿勢は排他的で、綴れるのは 1 つだけです。

Google Cloud の外の認証

Google Cloud の外では、認証だけが 2 つ目の経路を持ちます。OCHAKAI_OIDC_ISSUER と OCHAKAI_OIDC_AUDIENCE を設定すると、デプロイが Bearer トークンを自分で検証します。署名・発行者・audience・有効期限を見ます。使うのは発行者が公開している公開鍵で、共有鍵系のアルゴリズムは受け付けないため、ここでも秘密は増えません。認可が生まれるわけではなく、発行者が請け合った相手は全部を読み書きできます。2 つは必ず対で設定します。片方だけは起動時エラーです。

この経路が読むのは Authorization だけです。おかげで v0.27.0 からは、OIDC を Cloud Run IAM の後ろにも置けます。到達は Cloud Run IAM が、誰であるかは自分の発行者が決める二重の関門になります。クライアントは Google のトークンを X-Serverless-Authorization に、発行者のトークンを Authorization に置きます。

ホスト型のアシスタントは、IAM で守られたデプロイには設計上届きません。ChatGPT や Claude Desktop のコネクタは、Google の identity を持ち込めません。手元でコマンドを起動できるクライアントは、gcloud auth login 済みの ochakai を通して届きます。Claude Code、Claude Desktop の mcp-stdio、Cursor などです。設定の書き方はガイド「エージェントを繋ぐ」にまとめてあります。

5. プロジェクトの外に出るもの

出るものは 1 つ、埋め込みの呼び出しだけです。セマンティック検索を有効にすると、ドキュメントの本文と、利用者の打った検索クエリが Vertex AI に送られてベクトルになります。送り先はこのデプロイ自身のプロジェクトと、動いているリージョンです。決定的なエンコーダが返すのはベクトルであって、テキストではありません。それ以外にテレメトリはなく、外部に問い合わせるものもありません。

Cloud Run 上では、ochakai がメタデータサーバーから自分のプロジェクトとリージョンを読み、製品既定のモデル(gemini-embedding-001)で埋め込みを有効にします。設定する変数はなく、実際に呼べるかどうかは IAM が決めます。roles/aiplatform.user が無ければ、起動時の問い合わせが失敗し、ログ一行を残して、字句検索だけで動きます。

拒むなら、role を付与しないままにするか、そう明示します。

gcloud run services update ochakai --region=$REGION \
  --update-env-vars=OCHAKAI_EMBEDDINGS=off

付与する前に 1 つ。ochakai には認可がないため、サービスに届く誰もが、書き込むことで Vertex AI の呼び出しを起こせます。キュレーションされた知識ベースの規模では数セントです。付与すれば検索はハイブリッド(字句 + ベクトル)になり、日本語で書かれた知識ベースほど効きます。後で使えなくなっても、字句検索に落ちるだけです。

字句検索だけでどこまで落ちるかは測ってあります。CI の golden set は、同じ 88 問を字句のみでも走らせています。無関係な 2 つのドメインにまたがる 29 ドキュメントの知識ベースで、recall@10 は 1.00、MRR は 0.91(1 位 74 問、3 位以内 85 問)でした。日本語を二文字の窓で引くのは字句側の機構です。

この数字は 2 つ添えて読んでください。測ったのは 29 ドキュメントの知識ベースで、この設計が想定している数千ではありません。数が増えれば薄まるため、上限に近い床です。埋め込みが何を足すかも、この数字では測れません。言えるのは「Google Cloud の外でも日本語の検索は立つ」までで、「埋め込みは要らない」ではありません。

role を付ける前や、モデルを変えた後に読み込んだ知識は、埋め込みを持たないままになります。ochakai reembed が埋め直します。別のモデル・リージョン・プロジェクトを使うなら、変数は同じ 1 つで、値が Vertex AI のモデル resource name になります。それはセマンティック検索を要求する綴りで、使えなければ起動を拒否します。

スクリーンショットや PDF を検索対象にするなら、実体は GCS バケットに置きます。メタデータとリビジョンは Postgres に残り、認証はサービス identity 経由でキーはありません。OCHAKAI_GCS_BUCKET が無いと、そのインスタンスは markdown 専用で動き、ファイルの書き込みは 501 を返します。v0.27.3 からは、それをデプロイ自身が言います。ochakai stats が一行印字し、web UI はファイルを足す面を描きません。バンドル全体を持つ呼び出し元にだけ、変数の名前が載ります。

6. 運用

バックアップは二種類ある

どちらかがもう一方を含むわけではありません。

Cloud SQL バックアップは運用のためのもので、デプロイをその時点の状態に戻します。OKF export は可搬性のためのもので、ochakai より長生きするコピーです。

アップグレード

マイグレーションは起動時に自動で走るため、アップグレードとは新しいイメージタグのことです。先に読むのは changelog で、破壊的変更に印が付き、運用担当者が何をすべきかが書かれています。

gcloud run services update ochakai --region=$REGION \
  --image=$REGION-docker.pkg.dev/$PROJECT_ID/ghcr/na0fu3y/ochakai:<new-tag>

付いてくる罠が 2 つあります。

• web UI は API より前か、API と同時に上げます。決して後にしてはいけません。委譲用のヘッダーの名前が dual-accept の窓なしに変わった版があり、古い web UI が新しい API の前に立つと、今の綴りのヘッダーをそのまま素通りさせます。400 ではなく、静かな書き込みの誤帰属になります。
• トラフィックを前のリビジョンに戻しても、データベースのマイグレーションは戻りません。マイグレーションは追加的です。古いバイナリは新しいスキーマに対しても動き続けます。

デプロイしようとしているものは検証できます。イメージは SBOM と SLSA provenance 付きで公開されています。gh attestation verify oci://ghcr.io/na0fu3y/ochakai:<tag> -R na0fu3y/ochakai がそれを確かめます。Artifact Registry のリモートリポジトリは digest を変えないため、GHCR の attestation は動かすものに対してそのまま有効です。

週に一度、見るもの

デプロイの健康より、知識の側が静かに失敗します。レビューキューを誰も開かなくなっても、エラーは出ません。ochakai stats が、3 つのキューの中身を 1 回で返します。

ochakai stats                 # 3 つのキュー、フロー、返らなかった問い
ochakai stats --exit-code     # cron 用: 未処理のレビューが残っている間は 2 で終了する

3 つのキュー(未レビューの draft、failed と報告されたドキュメント、期限切れ)は、それぞれ一覧表示のコマンドを添えて出ます。空け方とレビューの順番は「育てて、回す」§4 です。

どこまでの規模か

大半は測っていません。ドキュメント数の天井も、スループットも、並行時のレイテンシ分布もありません。設計が想定しているのは、残らず人を通った数千のドキュメントです。

デプロイ手順が --max-instances=1 を設定しているのは、正しさではなくコストの決定です。上げるときに見る天井はデータベースの接続数で、各インスタンスは自分のプールを開き、既定は 4 接続(CPU が多ければその数)です。db-f1-micro は shared-core で上限が小さいため、SHOW max_connections で収まるかを確認します。収まらないなら OCHAKAI_DATABASE_URL に pool_max_conns を設定します。

7. やめるとき

先に知識を取り出します。全ドキュメントが OKF(フロントマター付きの markdown)のまま出てくるため、git に置けます。来歴とリビジョン履歴も残したいなら、上の表のとおり Cloud SQL バックアップの側で取ります。

ochakai export ./knowledge          # ディレクトリに展開する
ochakai export - > okf.tar.gz       # tar.gz で受け取る
ochakai export --prefix teams/growth -   # 1 つのディレクトリだけ。バックアップではない

3 つ目はバックアップではありません。v0.27.0 からの機能で、そのディレクトリを読める人なら誰でも取れます。共有しているデプロイの中の一チームが、管理者を通さずに自分の分を持ち出すためのものです。取り出したものは、根の index.md の bundle_scope と ochakai-okf-teams-growth.tar.gz というファイル名で、自分が部分であることを示します。全体のバックアップは --prefix を付けない形で、管理者だけが取れます。

そのうえで、作ったものを消します。

gcloud run services delete ochakai --region=$REGION --quiet
gcloud run services delete ochakai-webui --region=$REGION --quiet
gcloud sql instances delete ochakai --quiet

Terraform で立てたなら terraform destroy です。どちらの場合も、出しておいたバンドルは次の道具にそのまま持っていけます。