AWS‐Bedrock‐for‐Biblio‐Squad - krugle-jp/Krugle-Library GitHub Wiki

Krugle Biblio/Squad から AWS Bedrockモデル を利用する

1. 目的

本手順書では、Krugle BiblioやSquad から AWS Bedrock 上のモデルを利用できるようにするための設定手順を説明します。

Krugle Biblio/Squad は OpenAI 互換プロトコルとAnthropic互換プロトコルに対応しており、AWS Bedrock の bedrock-mantle エンドポイントも OpenAI 互換インターフェースとAnthropic互換インターフェースを提供しています。

そのため、LiteLLM などの中継プロキシを用意せず、Krugle Biblio/Squad から bedrock-mantle に直接接続できます。

Krugle Squad sandbox
  ── OpenAI protocol ──>
bedrock-mantle endpoint
  ──>
Kimi K2.5

2. 前提条件

以下を準備してください。

  • AWS アカウント
  • Bedrock のモデル呼び出し権限を持つ IAM ユーザー
  • AWS CLI
  • 対象リージョン：ap-northeast-1
  • Krugle Biblio/Squad の .env を編集できる環境

本手順では、東京リージョン ap-northeast-1 を使用します。

3. IAM ユーザーに最小権限ポリシーを付与する

専用の IAM ユーザーを作成し、以下のポリシーを付与します。

Kimi K2.5 は Marketplace 経由のモデルであるため、初回呼び出し時にアカウント単位でサブスクライブされます。
そのため、aws-marketplace:Subscribe 権限が必要です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockInvokeOnly",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:Converse",
        "bedrock:ConverseStream",
        "bedrock:ListFoundationModels",
        "bedrock:GetFoundationModel"
      ],
      "Resource": "*"
    },
    {
      "Sid": "MarketplaceSubscribe",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:Subscribe",
        "aws-marketplace:ViewSubscriptions"
      ],
      "Resource": "*"
    }
  ]
}

補足として、従来の「Model access」有効化画面は廃止されています。
現在は、サーバーレスモデルは初回呼び出し時に自動的に有効化されます。Marketplace モデルについても、権限を持つユーザーが初回呼び出しに成功すると、アカウント全体で有効化されます。

つまり、実質的には モデルの有効化 = 初回呼び出しの成功 です。

4. Access Key を作成し、Bedrock Runtime の呼び出しを確認する

IAM ユーザーの画面で、以下の手順により Access Key を作成します。

  1. IAM ユーザーを開く
  2. Security credentials を開く
  3. Access keys から Access Key を作成する
  4. Use case は Application running outside AWS を選択する
  5. Access Key ID と Secret Access Key を安全な場所に保存する

Secret Access Key は作成時に一度しか表示されないため、必ず控えてください。

5. AWS CLI に認証情報を設定する

AWS CLI が未導入の場合は、事前にインストールしてください。
macOS の場合は以下で導入できます。

brew install awscli

AWS CLI に認証情報を設定します。

aws configure

入力例は以下です。

AWS Access Key ID:      <Access Key ID>
AWS Secret Access Key:  <Secret Access Key>
Default region name:    ap-northeast-1
Default output format:  （空欄で可）

6. Kimi K2.5 の初回呼び出しを実行する

以下のコマンドを実行し、Kimi K2.5 を Bedrock Runtime 経由で呼び出します。

aws bedrock-runtime converse \
  --model-id moonshotai.kimi-k2.5 \
  --messages '[{"role":"user","content":[{"text":"hi"}]}]' \
  --region ap-northeast-1

正常に実行されると、assistant の応答を含む JSON が返却されます。

このレスポンスが返れば、以下が確認できたことになります。

  • IAM 権限が正しく設定されている
  • AWS アカウントで Kimi K2.5 が有効化されている
  • Marketplace モデルのサブスクライブが完了している
  • Bedrock Runtime 経由で Kimi K2.5 を呼び出せる

初回呼び出し時は、バックグラウンドでサブスクライブ処理が行われるため、通常より数秒長くかかる場合があります。

7. Bedrock API Key を発行する

bedrock-mantle エンドポイントは、AWS Access Key / Secret Access Key による SigV4 署名ではなく、Bedrock API Key を使用します。

これは前の手順で作成した IAM Access Key とは別のキーです。

以下の手順で Bedrock API Key を発行します。

  1. AWS マネジメントコンソールで Bedrock を開く
  2. API keys を開く
  3. 長期利用用の API Key を生成する
  4. 生成された API Key をコピーして安全な場所に保存する

この Bedrock API Key は、後続の Krugle Squad 設定で LLM_API_KEY として使用します。

8. bedrock-mantle への直接接続を確認する

以下の curl コマンドで、OpenAI 互換エンドポイントに直接リクエストを送信します。

curl https://bedrock-mantle.ap-northeast-1.api.aws/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEDROCK_API_KEY" \
  -d '{
    "model": "moonshotai.kimi-k2.5",
    "messages": [
      {
        "role": "user",
        "content": "hi"
      }
    ]
  }'

OpenAI 互換形式の JSON レスポンスが返れば、以下の経路が正常に動作しています。

curl
  → bedrock-mantle
  → Kimi K2.5

9. Krugle Squad の環境変数を設定する

Krugle Squad の .env に、以下の値を設定します。

OpenAI APIを利用したモデルの場合

LLM_API_KEY=<Bedrock API Key>
LLM_API_BASE_URL=https://bedrock-mantle.ap-northeast-1.api.aws/v1
LLM_NAME=moonshotai.kimi-k2.5　#任意のモデル名
LLM_PROVIDER=openai

Anthropic APIを利用したモデルの場合

LLM_API_KEY=<Bedrock API Key>
LLM_API_BASE_URL=https://bedrock-mantle.ap-northeast-1.api.aws/anthropic
LLM_NAME=anthropic.claude-haiku-4-5　#任意のAnthropicモデル名
LLM_PROVIDER=bedrock

各項目の意味は以下の通りです。

項目 設定内容
LLM_API_KEY Bedrock コンソールで発行した Bedrock API Key
LLM_API_BASE_URL bedrock-mantle の OpenAI 互換エンドポイント
LLM_NAME 使用する Bedrock モデル ID
DISABLE_LLM_PROXY 通常はコメントアウトしたままにする

LLM_API_KEY には、IAM の Access Key ではなく、Bedrock API Key を指定してください。

Biblioの.env

OpenAI APIを利用する場合

### MULTI MODAL LLM
MULTI_MODAL_LLM_BINDING=openai
MULTI_MODAL_LLM_MODEL=moonshotai.kimi-k2.5
MULTI_MODAL_LLM_BINDING_HOST=https://bedrock-mantle.ap-northeast-1.api.aws/v1
MULTI_MODAL_LLM_BINDING_API_KEY=<Bedrock API Key>


### LLM Binding type: anthropic, openai, ollama, lollms, azure_openai
LLM_BINDING=openai
LLM_MODEL=moonshotai.kimi-k2.5

LLM_BINDING_HOST=https://bedrock-mantle.ap-northeast-1.api.aws/v1
OPENAI_API_KEY=<Bedrock API Key>
LLM_BINDING_API_KEY=<Bedrock API Key>

Anthropicモデルを利用する場合

### MULTI MODAL LLM
MULTI_MODAL_LLM_BINDING=bedrock
MULTI_MODAL_LLM_MODEL=moonshotai.kimi-k2.5
MULTI_MODAL_LLM_BINDING_HOST=https://bedrock-mantle.ap-northeast-1.api.aws/anthropic
MULTI_MODAL_LLM_BINDING_API_KEY=<Bedrock API Key>


### LLM Binding type: anthropic, openai, ollama, lollms, azure_openai
LLM_BINDING=bedrock
LLM_MODEL=anthropic.claude-haiku-4-5

LLM_BINDING_HOST=https://bedrock-mantle.ap-northeast-1.api.aws/anthropic
ANTHROPIC_API_KEY=<Bedrock API Key>
LLM_BINDING_API_KEY=<Bedrock API Key>

10. 動作確認

Krugle Squad を起動または再起動し、チャットまたはエージェント実行から簡単な問い合わせを行います。

例：

こんにちは

正常に応答が返れば、Krugle Squad から Bedrock Kimi K2.5 への接続は完了です。

注意事項

1. OpenAI プロトコルを使用する

現時点では、OpenAI プロトコルでの接続のみが確認されています。

そのため、LLM_API_BASE_URL は必ず以下のように /v1 を含む OpenAI 互換パスを指定してください。

LLM_API_BASE_URL=https://bedrock-mantle.ap-northeast-1.api.aws/v1

Anthropic プロトコルでの接続の場合、必ず/anthropcを含むURLを指定してください。

LLM_API_BASE_URL=https://bedrock-mantle.ap-northeast-1.api.aws/anthropic

2. bedrock-runtime と bedrock-mantle のクォータは別

Step 6 の aws bedrock-runtime converse が成功しても、bedrock-mantle 側のクォータが十分であるとは限りません。

本番利用前には、bedrock-mantle 側の推論クォータも確認してください。

3. モデルのライフサイクルに注意する

Moonshot 側では K2.6 などの新しいモデルが提供されている場合がありますが、Bedrock 上での提供状況やライフサイクルは AWS Bedrock 側に依存します。

運用時は、Bedrock のモデルカードや提供状況を確認してください。

4. API Key の管理に注意する

Bedrock API Key が漏えいすると、第三者に Bedrock の利用枠を消費される可能性があります。

以下を徹底してください。

  • API Key を Git などのバージョン管理にコミットしない
  • .env の取り扱いに注意する
  • パスワードマネージャーなどで安全に保管する
  • 専用の IAM ユーザーを使用する
  • 不要になった API Key は削除またはローテーションする

エンドポイント・設定値一覧

項目 値
リージョン ap-northeast-1
モデル ID moonshotai.kimi-k2.5
mantle エンドポイント https://bedrock-mantle.ap-northeast-1.api.aws/v1
runtime エンドポイント https://bedrock-runtime.ap-northeast-1.amazonaws.com
コンテキスト長 256K tokens
最大出力 16K tokens

まとめ

本手順では、Krugle Biblio/Squad から AWS Bedrock の Kimi K2.5 を利用するために、以下を実施しました。

  1. IAM ユーザーに Bedrock 呼び出し権限と Marketplace サブスクライブ権限を付与
  2. AWS CLI で Bedrock Runtime の初回呼び出しを実行
  3. Bedrock API Key を発行
  4. bedrock-mantle の OpenAI 互換エンドポイントへの直接接続を確認
  5. Krugle Biblio/Squad の .env に OpenAI プロトコル用の設定を追加

この構成では LiteLLM などの追加プロキシは不要で、Krugle Biblio/Squad から bedrock-mantle を経由して Kimi K2.5 を直接利用できます。