メインコンテンツまでスキップ

トラブルシューティング

AI スタックは docker compose ひとつです。だからトラブルシューティングの出発点もひとつです — どのコンテナがおかしいかを見つけ、そのコンテナのログを見る。

cd /opt/kopens/plantpulse-ai-docker/bin
./doctor.sh      # 아무것도 바꾸지 않고 진찰만 합니다. 장애 중에 먼저 돌리십시오
./status.sh      # 무엇이 떠 있나
./health.sh      # 디스크 · 자원 · 서비스별 최근 로그까지

スタックが起動しません​

兄弟リポジトリが2つあるか​

ls /opt/kopens
# plantpulse-ai-docker
# plantpulse-ai-inference-server        ← 없으면 compose 가 뜨지 않습니다
# plantpulse-timeseries-insight-server  ← 없으면 compose 가 뜨지 않습니다

compose がこの2つのファイルを相対パスで bind-mount します(例:ゲートウェイ設定 litellm-config.yaml)。 無ければインストーラが起動を拒否し、欠けているリポジトリ名を出力します → インストール概要

設定ファイルがあるか​

sudo test -f /etc/kopens/plantpulse-ai.env && echo 있음 || echo 없음

無ければ bin/install.sh をもう一度実行するか、compose/env.gb10.example をそのパスにコピーします。

🔴 compose/.env を直接編集しないでください。 誰も読みません — 正本は /etc/kopens/plantpulse-ai.env です。

起動前判定が立っているか​

bin/up.sh · restart.sh · update.sh は compose を上げる前に env ファイルを判定し、食い違っていればコンテナを一つも 作らずに止まります。2026.10 で最もよくあるのは2つです。

cd /opt/kopens/plantpulse-ai-docker
sudo bash bin/lint-env.sh     # 줄마다 제자리인지 — 바꾸지 않습니다
出力原因対処
lines that do not belong in … と行ごとに release · profile · redundant · derived · unknown2026.09 以下の env をそのまま上げた — イメージ参照・GPU 割当・デフォルト値と同じ値・PP_HOST・旧 Platform アカウント行が残っている出力された sed 一行で消します。消す前に Platform 認証情報の2つの値を入れます → 環境変数設定
renamed keys still use their old names旧名 CH_* が残っている消さずに出力された sed(名前のみ変更)を実行します → 下記「CH_ 接頭辞」
PP_HW_PROFILE is not setハードウェア種別行が無いGB10 なら PP_HW_PROFILE=gb10、AWS g7e なら g7e を入れます
still has template placeholdersCHANGE_ME_* が残っている出力されたキーを埋めます。公開テンプレートに書かれた値では起動しません
[FATAL] [platform-credentials] …起動前 DB プロビジョニングが Platform 認証情報を受け取れなかった下記「コンテナが FATAL で止まります」と同じ原因です
PI_INBOUND_API_KEY is empty and PI_INBOUND_AUTH_DISABLED is not trueインバウンドキーが空です下記「バックエンドサービスが起動を拒否します」
PI_MEDIA_ENABLED=<value> — true 또는 false 만 받는다映像・音声スイッチに異なる値を書いたtrue か false で修正します → 映像・音声収集
行リストに ASR_URL … mediaホスト env の ASR_URL が映像・音声スイッチが与える値と異なるその行を消します。録音を有効化するのは PI_MEDIA_ENABLED=true 一行です

[warn] として出力される行(lines to tidy — the stack starts as is)は起動を妨げません — 旧名 MEDIA_INGEST_ENABLED (今回のリリース中はエイリアス、alias)、スイッチと同じ値の ASR_URL(media-same)、新名と同じ値で残っている旧行(oldname)です。 一緒に出力された sed 一行で整理します。エイリアスは 2026.11 に撤去されるので、その前に移行してください。

compose 自体が要求する値(PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY · PP_HW_PROFILE など)が空かどうかは こう確認します。

docker compose --env-file /etc/kopens/plantpulse-ai.env -f compose/docker-compose.yml config >/dev/null

コンテナが一つ再起動を繰り返します​

docker compose ps                              # 어느 것이 Restarting 인가
docker compose logs --tail=200 <컨테이너>       # 왜 죽는가
よくある原因確認
GPU をつかめないnvidia-smi · docker compose logs plantpulse-llm
Platform DB に接続できない下記「Platform DB」
メモリ不足docker stats · dmesg -T | grep -i oom
ポート競合ss -ltnp | grep -E '80|443|4000|5959|5960|7115|8970' — インストーラがすでに«他プロセスが使用中のポート»で警告している場合があります → サービスポートマップ
Platform 認証情報を受け取れない下記「コンテナが FATAL で止まります」
バックエンドサービスが inbound · INBOUND_API_KEY is empty で止まる下記「バックエンドサービスが起動を拒否します」
コパイロットだけ起動拒否下記「コパイロットだけ起動しません」

コンテナが FATAL で止まります — Platform 認証情報​

2026.10 以降、コパイロット・時系列インサイト API・LightRAG・RAG API・デジタルスレッド・LiteLLM は起動時に Platform からアカウント・パスワードを受け取ります。 受け取れない場合は前回の値で起動せず、FATAL で止まります — なのでこの6つのうち複数が一斉に再起動を繰り返すなら、まずここを見てください。

docker logs --tail=50 plantpulse-copilot-web 2>&1 | grep -iE 'credentials|fatal'
sudo grep -E '^PP_DATALAKE_ADMIN_(URL|API_KEY)=' /etc/kopens/plantpulse-ai.env
ls -l /etc/kopens/ca/root.crt /etc/kopens/ca/CA.crt
原因対処
PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY のうち片方だけある両方入れます。片方だけだとコンテナが拒否します
/etc/kopens/ca/root.crt が無いPlatform 信頼アンカーを置きます(同じ内容を CA.crt にも)。証明書検証を無効化する方法はありません
キーが間違っている、または AI ホスト IP が Platform の許可リストに無い(4xx)Platform ホスト /etc/kopens/plantpulse-platform.env の PP_DATALAKE_ADMIN_API_KEY をそのまま移し、許可リストに AI ホスト IP を入れます。4xx は再試行無しで即座に止まります
Platform :4950 に届かない・5xxしばらく再試行した後に止まります。curl -sk https://<플랫폼 호스트>:4950 に届くかから確認します

ホストスクリプト(起動前 DB プロビジョニング・install.sh START=1 の事前確認)も同じ値を受け取ります。そこで失敗すると コンテナが起動する前に [FATAL] [platform-credentials] … 一行が理由を伝えて止まります — 対処は上の表と同じです。

受け取りに成功すると、ログに credentials: で始まる行がキーの名前と個数のみを出力します。値を修正した後は bin/restart.sh で作り直します → インストール概要

バックエンドサービスが起動を拒否します — インバウンドキー​

RAG・時系列インサイト API・文書理解・ビジョン・デジタルスレッドはインバウンドキーが空だと起動しません(2026.10 再リリース前は 認証無しで開いたまま healthy で起動していました)。

sudo grep -c '^PI_INBOUND_API_KEY=.' /etc/kopens/plantpulse-ai.env     # 1 이면 값이 있습니다
docker logs --tail=50 plantpulse-rag-api 2>&1 | grep -iE 'inbound|fatal'
症状原因対処
bin/up.sh がコンテナを一つも作らず [fail] PI_INBOUND_API_KEY is empty … を出力するenv に行が無いか値が空 — 起動前判定が止まりますsudo bin/passwd.sh --generate PI_INBOUND_API_KEY で入れます(ファイルを直した後にスタックを再度上げます)
[fail] PI_INBOUND_AUTH_DISABLED=<value> — write true or false無認証スイッチに異なる値を書いたtrue · false で直すか行を消します
ログに FATAL: RAG_INBOUND_API_KEY is empty — refusing to start … のような行コンテナに空のキーが入った — compose を迂回して起動したか、イメージを別個に動かした上記のとおりキーを入れ bin/restart.sh で作り直します
スタックは起動するが管理コンソール・チャットの RAG・時系列呼び出しが 401キーを変更した後に一部だけ作り直したbin/restart.sh で全体を作り直します — 下記「管理コンソールが 502・upstream_auth」

認証無しで起動する方法は開発用スイッチ PI_INBOUND_AUTH_DISABLED=true ひとつのみで、キーがあればそのスイッチは無視されます ([note] … is ignored — PI_INBOUND_API_KEY is set and the key wins)。本番環境ではキーを入れるのが答えです → 環境変数設定

コパイロットだけ起動しません — 保存認証情報暗号化キー​

残りのスタックは正常なのに plantpulse-copilot-web だけ起動を拒否するなら PI_COPILOT_SECRET_KEY を見ます。

docker logs --tail=50 plantpulse-copilot-web 2>&1 | grep -iE 'SECRET_KEY|secrets'
ログ原因対処
PI_COPILOT_SECRET_KEY=… 一行を入れるよう出力キーが無いか形式が間違っている — 2026.09 以下から上げたホストには行がありません(インストーラは既存 env に追加しません)openssl rand -base64 32 の値で入れて作り直します → 環境変数設定
Stored secrets cannot be decryptedキーが変わったのに旧値を渡していない旧値を PI_COPILOT_SECRET_KEY_PREVIOUS に置きます → 交換手順。旧値を失った場合はログが出す SQL で封じられた行を空にして、その認証情報を画面から再入力します

デジタルスレッドの PI_DT_SECRET_KEY が空だとスタックは起動し、コネクタレジストリのみが config_error(503)で応答します。 起動前判定(bin/lint-env.sh)が2つのキーが欠けているかを«保存認証情報暗号化キーが無い»として知らせます。

設定を変えたのにコパイロットが無視します — CH_ 接頭辞​

2026.10 でコパイロット環境変数の接頭辞が**CH_ → CO_**に変わり、フォールバックはありません。 以前の env の CH_API_V1_KEY · CH_LLM_MAX_COMPLETION_TOKENS · CH_OTEL_GENAI_CONTENT のような行はコパイロットが読み込みません。 行を消すだけで値はデフォルトに戻ります — 例えば CH_API_V1_KEY で呼んでいた外部連携は、そのキーでは もう入ってこなくなります。

起動前判定はこれらの行を renamed として捉え起動を止め、行ごとに名前のみ変更する sed 一行を出力します(値は そのまま、バックアップを残す)。それを実行して bin/restart.sh plantpulse-copilot-web で作り直します。

cd /opt/kopens/plantpulse-ai-docker
sudo bash bin/lint-env.sh 2>&1 | grep -A2 'renamed'

旧名と新名の両方があり値が異なる場合は新名が優先されます — どちらの値が正しいか確認した後に旧行を消します → 環境変数設定

起動後にログが残らない・書き込みが失敗する — ボリューム所有権​

2026.10 から、コンテナは plantpulse-dcgm 一つを除き全て非root で動きます(当社イメージは uid 10001、gid 0)。 旧インストールで root により作られた書き込みボリューム(アプリログ・時系列ファインチューニング重み・LightRAG・Qdrant・Neo4j・Phoenix ストレージ、 vLLM キャッシュ、プロキシ証明書)にはそのまま書き込めません。その失敗はたいてい静かで(ログファイルの代わりにコンソールにだけ残る形)、 Qdrant はすぐ死に、プロキシは証明書キーを読めず処方を出して止まります。

bin/up.sh · restart.sh · update.sh は上げる前に bin/volumes-nonroot.sh で所有権を一度合わせます。 docker compose up を素手で呼んだ場合、この段階を飛ばしたことになります。

cd /opt/kopens/plantpulse-ai-docker/bin
./volumes-nonroot.sh     # 이미 맞으면 아무것도 바꾸지 않습니다
./restart.sh

合わせられなければ 볼륨 소유권을 <uid:gid> 로 맞추지 못했다 を出力して起動を止めます → サービス運用

Platform DB に接続できません​

🔴 AI スタックは PostgreSQL・Aster TSDB・Redis・RustFS を起動しません。 Platform のインストール本体を共用で使います。この4つが死ねば AI も一緒に止まります。

# 플랫폼 호스트는 이 URL 의 호스트입니다 (PP_HOST 는 따로 적지 않습니다)
sudo grep -E '^PP_DATALAKE_ADMIN_URL=' /etc/kopens/plantpulse-ai.env

# 실제로 닿는가
nc -zv <플랫폼 호스트> 5432    # PostgreSQL
nc -zv <플랫폼 호스트> 9042    # Cassandra

届かなければPlatform 側の問題です → サービスポートマップ

Platform アカウントは env にありません (2026.10)

PG・Aster TSDB・Redis・RustFS のアカウント・パスワード・ポートは、コンテナもホストスクリプトも開始時に Platform から 受け取ります。 認証が拒否された場合、env ではなくPlatform 側の値と上記「コンテナが FATAL で止まります」を見てください。 Platform でパスワードを変更した場合、AI コンテナを再起動しないと新しい値を受け取れません。

管理コンソールが 502・upstream_auth を出します​

コンソール画面の一つのメニューが … rejected the console's inbound API key (401) - check <변수> で失敗する場合、コンソールの 裏のサービスがコンソールのインバウンドキーを拒否したことを意味します — コンソールセッションの失効ではありません。以前の版はこの 401 を セッション失効と読んでログイン画面にばかり戻していました(再ログインしても同じでした)。

バックエンドとコンソールが同じ PI_INBOUND_API_KEY で起動しているかが原因です。片方だけ作り直したか、キーを変えた後に 一部だけ再起動した場合がほとんどなので、スタック全体を作り直します。

cd /opt/kopens/plantpulse-ai-docker && bin/restart.sh

管理コンソールのアドレスは 2026.10 から http://<AI 서버>:5959 · https://<AI 서버>:5960 です(以前は 9080)。

LLM 画面が 502・llm_upstream を出します​

コンソールの LLM 読み取り画面(API キー・ログ・モデル登録一覧・アップストリーム状態など)が 502 と事由 llm_upstream で 失敗する場合、ゲートウェイ(LiteLLM)かその DB が 5xx を出したことを意味します — コンソールバックエンドが壊れたわけではありません。応答の upstream_status がゲートウェイが出したステータスコードです。以前の版はこれを 500 としてそのまま流し、コンソール故障のように 見えていました。

docker compose logs --tail=100 plantpulse-litellm    # 게이트웨이가 왜 5xx 를 냈나 (DB 접속 등)

ゲートウェイに全く届かない場合は同じ 502 に事由が llm_unreachable です。4xx(入力エラー)はゲートウェイの事由が そのまま画面に出ます。

回答が出ません​

順番に絞り込みます — ゲートウェイ → モデル → 画面。

docker compose logs --tail=100 plantpulse-litellm    # 게이트웨이가 요청을 받았나
docker compose logs --tail=100 plantpulse-llm        # 모델이 답했나
docker compose logs --tail=100 plantpulse-copilot-web
症状よくある原因
ゲートウェイログにリクエストが無い画面側でゲートウェイアドレス・キーが間違っている
ゲートウェイが 401PI_LLM_API_KEY 不一致
外部連携だけがモデル名エラーで失敗旧名(aura-35b · gpt-4o · text-embedding-3-large など)を呼んでいる — 今は aura-lite · aura-embedding-4b です → API 連携ガイド
モデルが長くかかって切れるGPU メモリ不足 — nvidia-smi
「回答を作成できませんでした … モデルが空の応答を返しました」再試行してもモデルが空の回答を返しました(API では 502)。繰り返す場合は思考モードと生成上限を見ます → 環境変数設定
「⚠ 同じ内容が繰り返され、回答生成を中断しました」モデルが同じ発言を繰り返し、コパイロットが打ち切りました。質問を絞って再度尋ねます

「接続が切れました。サーバーは回答を作り続けています…」​

質問中に接続だけが切れたことを意味します(ネットワーク切替・プロキシ切断など)。新しい画面の文言は「接続が切れました。サーバーが回答を引き続き作成中で、 完了次第ここに読み込みます」です。サーバーは回答を最後まで作成して保存するため、画面はこの案内を出したまま 5秒ごとに、最大5分間、その会話の回答を再照会し、到着次第読み込みます。待てばよいです — スマートフォンでも同じです。 5分以内に見つからない場合はエラー案内に変わり再試行ボタンが残ります — この時は会話を再度開いて回答が 保存されたか先に確認してください。

文書が見つかりません (RAG)​

docker compose logs --tail=100 plantpulse-rag-api
docker compose logs --tail=100 plantpulse-lightrag
curl -s http://127.0.0.1:6333/healthz     # Qdrant(벡터 색인)
症状確認場所
チャットが「文書検索を今は使えません(MCP ゲートウェイ応答なし) …」と答えて回答しないチャットの文書検索は MCP ゲートウェイ経由でのみ 行われます。ゲートウェイが起動しているか — docker compose logs --tail=100 plantpulse-mcp-gateway-api、コパイロットログの [MCP_GATEWAY] unreachable・[DOC_SEARCH_GUARD]。同じとき、他の質問の回答の冒頭には「ツールゲートウェイに届きません …」が付きます
チャットが「文書検索ツールがオフになっているか、このアカウントに許可されていません …」と答えて回答しないゲートウェイは応答していますが rag_search がモデルに届いていません。AI 管理コンソール › MCP ゲートウェイ で サーバー の RAG Gateway と ツール の rag_search がオンになっているかを見ます(どちらも最初からオンなので、誰かがオフにしたということです)。オンになっていれば、その人のチャットツール権限(tool:mcp)とゲートウェイの «権限» タブを見ます → RAG — チャットの文書検索
入れた文書が検索に引っかからないインデックス作業が終わっているか — plantpulse-rag-api ログ・Sync History のスキップ理由 → RAG
文書アップロードが失敗するplantpulse-docling-serve · plantpulse-document-understanding-api
回答が見当違いの文書を引用するインデックスが古い — 再度入れてインデックス
AI が「文書から見つけられなかった」とだけ言う正常動作の可能性があります — 検索が空振りの場合、回答を作らず retrieved: false で返します。rag_list_documents でその文書がインデックスされているかから確認します
RAG /health が degraded応答の ingest · neo4j · qdrant のうち ok でないもの

大きな PDF がインデックス中に失敗します​

LightRAG は文書の断片ごとに LLM でエンティティを抽出します。一つの断片が時間内に終わらなければ文書全体が 失敗として残り、残りの断片は試行すらされません。

docker compose logs plantpulse-lightrag | grep -E 'Worker execution timeout|workers initialized'
ログ意味
extract LLM func: Worker execution timeout after 480s以前のデフォルト値(呼び出しあたり240秒)で動いているインストールです
(Timeouts: Func: 3600s, Worker: 7200s, …)現在のデフォルト値です

時間予算は /etc/kopens/plantpulse-ai.env の**LIGHTRAG_LLM_TIMEOUT(デフォルト3600秒)で、 実際の上限はその2倍です。チャットと問い合わせが集中しモデルが遅い時間帯にインデックスが切れる場合はこの値を見ます。 変更した後は再起動ではなく再生成**(bin/restart.sh)が必要です。

タイムアウトだけを増やさないでください

一断片の出力上限(LIGHTRAG_LLM_MAX_TOKENS、デフォルト32768)も一緒にかかっているため長い予算が安全です。 上限を消して予算だけ増やすと暴走した一つのリクエストが GPU スロットを一時間占有します。

文書・写真ツールが refused to fetch で失敗します​

文書理解・ビジョンツールは受け取った URL が**社内アドレス(ループバック・プライベートネットワーク・リンクローカル)**に解決される場合に拒否します。事由に resolves to a non-public address が見える場合はこのケースです。

社内ファイルサーバーをあえて開放するには、そのホスト名を FETCH_ALLOWED_HOSTS に記載し、両サービスを作り直します。 URL に使う名前そのまま(ポートを付ける場合はそのポートのみ)を書く必要があります。

echo 'FETCH_ALLOWED_HOSTS=files.example.local' | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
cd /opt/kopens/plantpulse-ai-docker
bin/restart.sh plantpulse-document-understanding-api plantpulse-vision-api

→ 環境変数設定 · MCP ツールマップ

図面が一般文書としてインデックスされる、または図面画面が出ません​

図面収集はデフォルトでオフです(DRAWING_INGEST_ENABLED=false)。オフの場合、rag-api に図面 API 自体が無く、 DXF・PDF 図面は図面として読み込まれません。

docker exec plantpulse-rag-api printenv DRAWING_INGEST_ENABLED

false ならホスト env に DRAWING_INGEST_ENABLED=true を記載し bin/restart.sh plantpulse-rag-api で作り直した後、 図面を再度アップロードします — 有効化する前にアップロードしたファイルは図面として再読み込みされません。PDF はアップロード時に種類を«図面»に 指定しないと図面として読み込まれません → 環境変数設定

コンソールが出す文言意味
drawing is platform-managed — update it in the platform, not here (409)Platform 資産文書として入ってきた図面をコンソールから上書きアップロードしようとしました(2026.10 再リリース3)。修正は Platform 側で行います
drawing is platform-managed — delete it in the platform ledger, or exclude it from RAG (POST …/exclude) (409)Platform 台帳図面をコンソールから削除しようとしました。削除は Platform 台帳側で行い、検索からのみ除外するには«コーパスから除外»します
manually uploaded drawings cannot be excluded — delete the drawing or re-index it instead (platform-ledger drawings can be excluded) (409)コンソールから直接アップロードした図面は«検索除外»ができません。削除するか再インデックスします。Platform 台帳図面は除外可能です
extension not allowed (400)DWG です。DXF か PDF にエクスポートしてアップロードします

チャットに追加したファイルを読み取れません​

質問の入力欄の ファイルを追加 で入れたファイルは、コパイロットが受け取ってオブジェクトストレージに置き、文書理解サービス(plantpulse-document-understanding-api)に 読み取らせます — 文書は docling で、図面は図面判読で、映像・音声は文字起こし(/api/v1/transcribe → plantpulse-asr)で。使い方は AI チャット — ファイルを追加 にあります。

docker logs --tail=200 plantpulse-copilot-web 2>&1 | grep -E '\[CHAT_ATTACH|\[attach\]|\[CHAT_MEDIA'   # 올림 · 판독 · 녹취 · 실패 사유
docker compose logs --tail=100 plantpulse-document-understanding-api
docker compose logs --tail=100 plantpulse-docling-serve
docker compose logs --tail=100 plantpulse-asr                       # 영상 · 음성 — PI_MEDIA_ENABLED=true 일 때만 뜹니다

アップロード時に拒否されるもの — チップに次の文がそのまま表示され、そのファイルは送信しません。

チップに表示される文原因・対処
「このファイル形式はアップロードできません。Office(xlsx·xls·csv·docx·pptx)·PDF·図面(DXF·PDF)·映像(mp4·mov·mkv·webm)·音声(m4a·mp3·wav)ファイルをアップロードしてください」受け付ける形式ではありません。形式は 内容 で判定するため、拡張子を変えるだけでは入りません
「映像·音声ファイルの名前と内容が一致しません …」拡張子は映像・音声なのに、ファイルの先頭がその形式ではありません。変換ツールで拡張子だけ変えたファイルなら、元の形式で書き出し直します
「映像·音声ファイルが大きすぎます(最大1GB)」映像・音声は 1GB までです。分割するか解像度を下げて入れます
「映像·音声が長すぎます(最大60分)。分割してアップロードしてください」60 分を超えています。先頭部分だけを受け付けることはしません — 分割して入れます
「現在、文字起こしを待っているファイルが多すぎます。しばらくしてから再度アップロードしてください」インストール全体で文字起こしを待っているかアップロード中の映像・音声が 4 個あります。前のものが処理されたら入れ直します
「DWG は読み取れません。DXF か PDF にエクスポートしてアップロードしてください」CAD で DXF か PDF にエクスポートして入れます
「写真は画像として添付してください(入力欄に置くと画像として添付されます)」写真ファイルが添付の経路で来ました。入力欄にもう一度入れると写真として添付されます
「ファイルが大きすぎます(最大50MB)」ファイル 1 つは 50MB までです。分割して入れます
「1つの対話にアップロードできるファイルは20個までです」この対話にすでに 20 個あります。新しい対話で入れます
「ファイルが空です」0 バイトのファイルです
「このファイルを読み取れませんでした: 破損しているか、最後まで受信できませんでした」ファイルが壊れているか、アップロード中に途切れました。元ファイルを開いて確認してから入れ直します
「ファイル構造が大きすぎるため受け付けませんでした(展開後のサイズ·項目数の上限)」Office ファイル内の項目が 2 万個を超えるか、展開後のサイズが 500MB を超えています
「ファイルを保存できませんでした。しばらくしてから再度アップロードしてください」オブジェクトストレージに書き込めませんでした。コパイロットのログとオブジェクトストレージの状態を確認します

アップロード後に判読が失敗したもの — チップに「このファイルを読み取れませんでした: 理由」が表示されます。理由はサーバーが残した英語の文です。このファイルは送信でき、 AI は «読み取れなかったファイル» として認識します。

理由原因・対処
document reader unreachable · drawing reader unreachable文書理解サービスに到達できませんでした。plantpulse-document-understanding-api が起動しているか確認します
document reader is not configuredコパイロットに文書理解サービスのアドレスがありません。既定の compose では起きません — 設定を手で変更していないか確認します
reading took longer than 10 min判読が 10 分を超えました。大きな PDF か、索引作業と重なったときです。ファイルを外して空いているときに入れ直すか、必要なページだけ切り出して入れます
too many files are being read — remove it and add it again同時に読み取っているファイルが多すぎます。チップを外し、しばらくしてから入れ直します
reading was interrupted — remove the file and add it again判読中にコパイロットが再起動しました(15 分以上進捗がないとこのように打ち切ります)。外して入れ直します
document reader answered 503 などの数字文書理解サービスが混雑しているか、キーが合っていません。文書理解のログを確認します
その他の文文書理解サービスが返した理由そのままです(例: 開けない古い Office ファイル)。元ファイルを PDF か新しい形式(xlsx · docx · pptx)で保存し直して入れます

映像・音声の文字起こしが失敗したもの — チップに「文字起こしできませんでした: 理由」または「受け付けませんでした: 理由」が表示されます。理由は文書理解サービスが返した英語の文そのままです。 接続・混雑のような一時的な失敗は 1・5・30 秒後に 3 回再試行してから失敗として打ち切り、設定・入力の問題はすぐに失敗として打ち切ります。 失敗したファイルも送信でき、原本も再生できますが、AI は «文字起こしできなかったファイル» として認識します。

理由原因・対処
media transcription is disabled: ASR_URL is not set映像・音声が無効のインストールです。管理者がホスト env に PI_MEDIA_ENABLED=true を入れ、文字起こしモデルを取得して再起動します → 映像・音声収集
media transcription is misconfigured: …文字起こしの設定が合っていません(サービング名など)。文書理解の /health とログを確認します
transcription service unreachable · transcription service answered 503 など文書理解サービスか文字起こしサービング(plantpulse-asr)に到達できなかったか、混雑していました。両方が起動しているか確認し、外して入れ直します
transcription service is not configuredコパイロットに文書理解サービスのアドレスがありません。既定の compose では起きません
「受け付けませんでした: …」(長さ超過)先頭から長さを読み取れずに受け付けたファイルが、文字起こしの途中で 60 分を超えました。分割して入れます
その他の症状原因
送信が押せず「ファイルを読み取り中です — 読み終えると送信できます」が残っている判読が終わっていません。読み終えるか失敗すると解除されます。読み取り中のファイルを外しても解除されます
「添付ファイルをまだ読み取り中です。読み終えてから送信してください」送信の瞬間、サーバーでまだ読み取り中のファイルがありました。チップが «読み取り済み» になってから送り直します
チップを押すと「このファイルが見つかりません。削除されたか、閲覧できないファイルです」ファイルが削除されたか、他人の対話のファイルです。添付は対話の所有者だけが開けます(管理者も同じです)
チップを押すと「ファイルを読み込めませんでした。しばらくしてから開き直してください」オブジェクトストレージから元ファイルか読み取った文を取得できませんでした
ファイルは «読み取り済み» なのに AI がファイルの内容を知らないと言うその人にチャットツール権限 tool:builtin がないと、AI は添付を読むツールを受け取れません → 権限
長い文書の後半を AI が知らない先頭 100 ページ(シート・スライドは 1 つを 1 ページとして)だけ読みます。必要な部分を切り出して入れます
PDF 図面の寸法・部品表を的外れに読む文書として読み取られています。チップの 図面 ボタンを押して図面として読み取らせ直してから送信します
映像を入れて尋ねたのに AI が「まだ文字起こし中」と言う文字起こしが終わっていません。5 分・200MB 以下は質問が 20 秒まで待ち、それより長いファイルはバックグラウンドで文字起こしします。「文字起こし完了」になってから尋ね直します
チップが長く「文字起こし待ち」のままになる文字起こしはインストール全体で一度に 1 つずつ、入れた順に行います(短いファイルが先)。前のファイルが終わるのを待ちます。ずっとそのままなら [CHAT_MEDIA のログを確認します
「話し声·字幕が見つかりませんでした」話し声も内蔵字幕もありません。画面上の文字・焼き込み字幕は読みません
映像が再生されないブラウザが開けないコーデック(例: H.265)です。文字起こしと回答はそのまま行われます
大きな映像をアップロード中に HTML 413 が表示されるプロキシのチャット添付の経路は 1040MB まで開いています(ホストの MEDIA_MAX_FILE_MB には従いません)。プロキシのイメージを手で変えていないか、前段に別のプロキシがないか確認します

音声での質問が「現在音声入力を使用できません」で終わります​

チャットの音声で質問は録音を文書理解サービスの録取入口に送り、文書理解が録取サービング(plantpulse-asr)を 呼び出します。この案内(「…録取サービスが停止しているかビジーです」)は、その経路のどこかが閉じていることを意味します。コパイロットログに 文書理解が出したステータスコードが残ります。

docker logs --tail=100 plantpulse-copilot-web 2>&1 | grep '\[voice\]'      # 예: [voice] doc-und answered 503: …
docker exec plantpulse-document-understanding-api printenv ASR_URL          # 비었으면 영상 · 음성이 꺼진 설치
cd /opt/kopens/plantpulse-ai-docker && bin/status.sh                        # plantpulse-asr · plantpulse-asr-audio
原因表示されるもの対処
映像・音声がオフ(デフォルト)文書理解の ASR_URL が空で、録取入口が 503(media transcription is disabled: ASR_URL is not set)ホスト env に PI_MEDIA_ENABLED=true を入れ録取モデルを受け取った後 bin/restart.sh → 映像・音声収集
有効化したのに文書理解が旧値で起動しているASR_URL が依然空スイッチを変更した後 docker restart ではなく bin/restart.sh で作り直します
plantpulse-asr が unhealthy・再起動を繰り返す文書理解 /health の components.asr.status が down、全体 status が degradeddocker logs plantpulse-asr — モデル(/opt/kopens/models/Aura-ASR-Turbo)が無ければ bin/fetch-models.sh で受け取ります。初回起動はコンパイルのため時間がかかることがあります
plantpulse-asr-audio が 0 以外のコードで終了したbin/status.sh で «Exited (0)» でない。これに依存する plantpulse-asr も起動しませんdocker logs plantpulse-asr-audio を見て、イメージが取得されているか確認した後 bin/restart.sh
録取サービングがビジー映像処理と重なった時間帯しばらくしてから再度行います

plantpulse-asr-audio が «Exited (0)» のまま残っているのは正常です — オーディオライブラリをボリュームに移して終わる 使い捨てサービスであり、bin/status.sh も正常として数えます。

他の案内原因
「音声入力は HTTPS アドレスでのみ使用できます」ブラウザは平文アドレスではマイクを許可しません。https:// で接続します
「マイク権限が拒否されました」アドレスバーの錠前アイコン → マイク«許可»
「録音が長すぎます(最大60秒)」・「録音が大きすぎます(最大4MB)」質問一回は60秒・4MB までです
「発話を認識できませんでした」録取が空の結果でした。マイクに近づいて再度話します

MCP ツールが見えません​

PP_API_URL · PP_API_TOKEN が空だとスタックは起動しませんが、トークンが間違っていればスタックは正常に起動し、チャットの Platform MCP ツールだけが0個になります。だから「故障」のようには見えません。

sudo grep -E '^PP_API_(URL|TOKEN)' /etc/kopens/plantpulse-ai.env

値を埋めた後は再起動ではなく再生成が必要です — docker restart は env を再度 読み込みません。

cd /opt/kopens/plantpulse-ai-docker && bin/restart.sh

時系列分析ができません​

docker compose logs --tail=100 plantpulse-timeseries-insight-api    # :8970
docker compose logs --tail=100 plantpulse-timeseries-insight-server # :8980 (호스트에는 안 열립니다)

この2つは Platform の Aster TSDB から値を読み込みます。上記「Platform DB」を先に確認してください。

予測が500になる、または全てNAIVEになる​

設定エラーはサーバーを落としません — 同じプロセスが異常検知もサービングするため、無関係な機能まで止まることはありません。まず推論サーバーの /health を見ます。

# 이 이미지에는 curl 이 없습니다 — python 으로 찌릅니다
docker compose exec plantpulse-timeseries-insight-server \
  python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8980/health').read().decode())"

models.ttm.loaded: false に status: "degraded" なら予測モデルが起動できていないことを意味し、error に理由が あります。models 項目が全く無い場合は以前の版なのでヘルスチェックでは見えません — 下記のログで 判別してください。

docker compose logs plantpulse-timeseries-insight-server | grep -E 'MODEL_LOAD|WARMUP|INFER_FORECAST|fallback naive'
ログ意味すべきこと
[MODEL_WARMUP_FAIL] TTM ch=… 설정이 체크포인트와 맞지 않는다チェックポイント世代とローダークラスが食い違っています。予測は500ですTS_TTM_MODEL_CLASS を空にする(チェックポイントが選ぶ)か世代に合わせます → 説明
[MODEL_LOAD_FAIL] … 무작위 초기화 모델로 대체하지 «않는다»同じ原因です。読み込みを拒否した箇所です上記と同じです
[MODEL_WARMUP_SKIP] TTM ch=…2026-09-21以前の版の同じ原因です。その版では予測が**200にmodel_used="NAIVE"**として出ます上記と同じです
TTM 을 돌릴 데이터가 모자라다 -> fallback naive. reason=…データ不足。200にNAIVEです — 現版はこれのみを単純外挿で吸収しますreason を読みます
TTM failed -> fallback naive. reason='<태그>_prediction_q0.1'全ての予測がNAIVEで返ります。R3重みは積まれているが分位数列名の修正が入っていないイメージです(例:2026.09-20260924-1004)修正済みイメージで再度取得します(./update.sh)
TTM failed -> fallback naive. reason=… (その他)以前の版のフォールバックです — その版はデータ不足以外の失敗も200NAIVEとして飲み込みましたreason を読みます

NAIVE で応答した場合、応答の fallback_reason にも同じ理由が含まれています — ログに入れない箇所ではそちらを見てください。

「全部NAIVE」と「500」は同じ病気の2つの版です

設定エラーが単純外挿に化ける問題を2026-09-21に修正しました。以前の版は /health 正常・予測200・全ての回答が静かに単純外挿のまま動くことがありました。どちらの版でも見るべき場所は同じです — 上記のログと TS_TTM_MODEL_CLASS です。

版番号で判別しないでください — 今月のイメージは 2026.09-<date>-<시각> で何度も焼き直されます。 上記のログ行が最も確実な判別法です。

設定を変えたのに数値が一つも変わりません​

それならその設定は反映されていません。 モデルライブラリのパラメータは知らない名前を静かに飲み込む場合があり、間違って与えた値がエラー無しで無視されます。実際、異常検知の集計・平滑化パラメータ(aggr_win_size · smoothing_window_size)がライブラリの引数名変更以降全て無視されたまま動いており(2026-07-24監査)、その間エラーも警告もありませんでした。

設定を変えたら«数値が変わったか»で確認してください

「エラーが出なかった」は確認になりません。変更前後のスコア分布や検知件数を比較し、一つも変わらなければ設定が届いていないと見てください。

極端な値で一度試してみるのが最も速いです — 値を大きく変えたのに結果が同じなら、その設定は届いていません。

ディスクが埋まります​

docker system df
df -h /data1

コンテナログは Docker が回転させるので手で消すものはありません。たいていはイメージとボリュームです。

docker image prune -f      # 태그 없는 옛 이미지
docker volume prune をむやみに実行しないでください

Neo4j・Qdrant・LightRAG ストレージがボリュームにあります。コンテナが停止している間に実行すると ナレッジグラフとベクトルインデックスが消えます。

緊急復旧​

cd /opt/kopens/plantpulse-ai-docker/bin
./restart.sh                       # 스택 전체. 0 이면 «쓸 수 있다» 는 뜻입니다
docker compose restart plantpulse-lightrag   # 하나만

イメージを新規取得してアップするには:

./update.sh
データの場所

LightRAG 原本文書・インデックス・ナレッジグラフは名前付き Docker ボリュームにあります (pi-lightrag-inputs · pi-lightrag-storage · pi-qdrant-data · pi-neo4j-data、2026.10から工場グラフ ミラーの pi-digital-thread-neo4j-data と時系列ファインチューニング重み pi-ttm-tuned-models)。 ホストディレクトリではないので rm -rf では消えず、反対に docker volume prune 一回で 一緒に消し飛びます。削除する前に必ずバックアップしてください — bin/backup.sh が compose ボリューム(ログ・キャッシュ除く)を取得します。

あわせて見る​