deepseek.ac日本語で学ぶ、実践する

運用

DeepSeek組み込みシステムの引き継ぎ設計 — 後任と後続システムに安全に渡す

· 約9分

リード

LLM組み込みシステムの引き継ぎは、通常のWebアプリより漏れやすい領域があります。コードは渡せても「どのモデル・どのプロンプト・どの鍵で動いていたか」が失われると、後任は再現も切り戻しもできません。この記事では、人への引き継ぎと後続システムへの移行の両方に使える最小セットを整理します。

前提

本文

「後続」は2種類ある

言葉が曖昧になりやすいので、最初に分けます。

どちらも「現行が何で動いているか」を第三者が再現できることがゴールです。LLMは同じコードでもモデルやパラメータで出力が変わるため、コード以外の前提を成果物として残す必要があります。なお、モデルID・API仕様・料金は変更されるので、本記事の具体的な値は必ず公式ドキュメントで確認してください。

台帳を1枚作る

まず handover.yaml のような単一ファイルを作ります。散在するWikiより、1ファイルをGit管理する方が差分が追えます。

system: support-bot
owners:
  current: ["alice"]
  next: ["bob"]

llm:
  provider: deepseek
  model_id: "公式ドキュメントのモデルIDを記載"
  base_url: "公式ドキュメント参照"
  params:
    temperature: 0.2
    max_tokens: 800
  # 出力が変わると困る箇所は「変更手順」を別途定義する
  change_policy: "eval通過後のみ更新"

secrets:
  store: "Secrets Manager"
  keys:
    - name: DEEPSEEK_API_KEY
      scope: "prod"
      rotation_days: 90
      owner: "platform-team"

prompts:
  path: "prompts/"
  version: "v1.4.2"   # ハッシュ or タグで固定

eval:
  dataset: "eval/golden_set_v3.jsonl"
  command: "make eval"
  baseline_score: 0.87

ops:
  budget_usd_per_month: 0      # 実額は実測値を記入
  rate_limit_rpm: 0            # 契約値・実測値を記入
  dashboard: "（監視URL）"
  runbook: "docs/runbook.md"

数値はダミーです。実額・実レート制限は契約と実測で埋める（推測で書くと後任が誤算します）。

秘密情報は「値」ではなく「置き場所と権限」を渡す

鍵をチャット・チケット・リポジトリ・議事録に書かないのが原則です。渡すのは次の3点セット。

  1. 保管場所（どのシークレットストアの、どの名前か）
  2. 権限付与の手続き（誰が承認するか）
  3. 失効・再発行の手順（旧鍵をいつ無効化するか）

受け入れ確認では、いきなり本番鍵を渡さず読み取り専用・別プロジェクトの鍵で疎通→評価→本番切替の順にします。切り分けができ、事故時の影響範囲も小さくなります。

設定の有無だけを確認するスクリプトは、値を出力しないようにします（長さや一部文字列も漏洩の手がかりになります）。

#!/usr/bin/env bash
set -euo pipefail

required=(DEEPSEEK_API_KEY DEEPSEEK_BASE_URL)

for k in "${required[@]}"; do
  if [[ -n "${!k:-}" ]]; then
    echo "OK   $k (set)"
  else
    echo "MISS $k"
  fi
done

プロンプトとモデル設定をバージョン管理下に置く

プロンプトをコードと別リポジトリに置くと、デプロイ時にズレます。同一リポジトリに置き、実行ログにプロンプト版とモデルIDを出すところまでやると、後任は「この応答がどの設定で出たか」を追えます。

import logging

logger = logging.getLogger("llm")

PROMPT_VERSION = "v1.4.2"
MODEL_ID = "公式ドキュメントのモデルID"

def log_call():
    # 値そのものではなく「版」を記録する
    logger.info(
        "llm_call",
        extra={"prompt_version": PROMPT_VERSION, "model": MODEL_ID},
    )

プロンプト改修の履歴は、コミットメッセージより**変更理由（何が困って変えたか）**が効きます。テンプレのPRに「変更理由 / 評価結果 / 切り戻し先の版」を必須項目として入れておくと引き継ぎ資料が自動で溜まります。

評価セットを残すのが一番効く

引き継ぎで最も効くのは、**ゴールデンセット（入力と期待する振る舞いの組）**です。これがあると後任はモデル更新やプロンプト変更を自己判断できます。無いと「触ると壊れる」状態になり、誰も保守できなくなります。

「モデル更新時に何を確認するか」をここに集約しておくと、運用が属人化しません。

コストとレート制限は「現在値」で記録する

トークン単価やレート制限は変わるので、記憶や古い記事を転記しないこと。台帳には確認日つきで書きます。

cost:
  checked_at: 2026-10-22
  source: "公式ドキュメントの該当URL"
  note: "キャッシュ利用時の扱いも要確認"

後任が最初にやるのは「今いくらかかっているか」の把握です。請求ダッシュボードのURLと、月次で見る指標（呼び出し回数・失敗率・平均トークン数）をセットで渡します。

切り戻し手順を文章で残す

LLM部分は「壊れたときに戻す」がしづらいので、手順を明文化します。

「フォールバックがある」と引き継ぎの心理的ハードルが下がります。LLMの品質問題は完全には防げないので、止め方を設計しておくのが実務的です。

つまずきポイント

症状 対処
後任が本番で疎通できない 秘密情報は「値」でなく「保管場所＋権限手続き」で渡す。読み取り専用鍵から
モデル更新後に出力が変わった 評価セットで差分を検出。変更ポリシーを台帳に明記
プロンプトがどこにあるか分からない コードと同一リポジトリに置き、実行ログに版を出す
費用が読めない 単価は公式で確認し、確認日つきで記録。ダッシュボードURLも渡す
触ると壊れそうで誰も保守しない ゴールデンセット＋make eval を整備する
障害時に止め方が分からない フォールバックと切り戻し手順を runbook に書く

まとめ

チェックリスト