DeepTutor ローカルデプロイメントチュートリアル: Docker、モデル構成、およびコード実行のセキュリティ設定

DeepTutor は、オープンソースのパーソナライズされた学習システムで、教材に関する質問、調査および学習計画を実行し、コードの実行を通じて DOCX、PDF、PPTX、および XLSX ファイルを生成できます。これは個人用学習アシスタントの構築に適していますが、ローカルに展開する場合は、モデル、検索、ファイルストレージ、およびコード実行権限を同時に処理する必要があります。

プロジェクトアドレス: HKUDS/DeepTutor

簡単な答え

最初のデプロイでは、バックエンドをホストに直接インストールするのではなく、リポジトリによって提供される Docker Compose 構成を使用することをお勧めします。 Compose ソリューションは、モデルによって生成されたコードを独立した低特権のランナーサイドカーに引き渡し、制限された子プロセスをホスト上で直接実行するよりも分離強度が高くなります。

導入前の準備:

Docker および Docker Compose;
少なくとも 1 つのサポートされているモデルの API キー。
オプションの埋め込みサービスと検索サービス。
永続的な data/ ディレクトリ。
アクセスアドレスは、信頼されたネットワーク上でのみ開かれます。

設定ファイルはどこにありますか?

DeepTutor のユーザー構成は data/user/settings/ にあります。一般的なファイルには次のものがあります。

ドキュメント	目的
`model_catalog.json`	LLM、埋め込み、検索サービス、API キー
`system.json`	ポート、CORS、SSL、添付ファイルディレクトリ、およびアップロードの制限
`auth.json`	ログインスイッチ、ユーザー名、パスワードハッシュ、およびセッション設定
`integrations.json`	PocketBase と Sidecar の統合
`interface.json`	言語、テーマ、インターフェイスの設定

当局は、ブラウザの設定ページからこれらのファイルを変更することを推奨しています。 JSON を手動で編集する場合は、既存の構成のセクション全体を上書きしないでください。まずバックアップして、カンマ、引用符、モデル ID を確認してください。

なぜコードの実行に注意を払う必要があるのでしょうか?

DeepTutor の Office スキルにより、モデルは Python スクリプトを生成し、exec または code_execution を通じて実行されます。これにより、python-docx、reportlab、openpyxl などのライブラリを使用してファイルを生成できるようになりますが、これはモデルがコードを実行できることも意味します。

ローカルで直接実行している場合、デフォルトの制限付きサブプロセスは依然としてホスト上にあります。 Docker Compose は、独立したランナーの使用を優先します。 Office ファイル生成機能が必要ない場合は、ホストのサブプロセスの実行を閉じることができます。

1

DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0

data/user/settings/system.json で sandbox_allow_subprocess を false に設定することもできます。オフにすると、コードの実行に依存するファイル生成機能が使用できなくなります。

推奨される展開チェック

まず 127.0.0.1 のみをバインドし、ページとモデルの呼び出しが正常であることを確認します。
解析をテストするために、プライバシーを保護せずに小さなファイルをアップロードします。
生成されたファイルがホストプロセスではなくランナーによって実行されるかどうかを確認します。
認証をオンにした後、リバースプロキシ経由で LAN アクセスを提供します。
アップロードサイズ、添付ファイルディレクトリ、CORS ソースを制限します。
API キーはサーバー構成にのみ配置され、パブリックリポジトリには書き込まれません。

3 つの動作モードから選択するにはどうすればよいですか?

DeepTutor のローカル実行は、直接実行、単一コンテナー、Docker Compose に大別できます。選択するときは、インストールコマンドを比較するだけでなく、モデル生成コードが実行される場所も比較してください。

方法	利点	主なリスク	適切なシナリオ
ローカルで直接実行	コードのデバッグと変更が簡単	制限された子プロセスはまだホストマシン上にあります。開発と信頼できるデータのテスト
単一コンテナ	集中した依存関係	アプリケーションとコードの実行は依然として同じコンテナ境界内にあります。シングルユーザーエクスペリエンス
Docker Compose	独立したランナー、より明確な分離	その他の構成アイテムとコンテナ	長期セルフホスティング

DOCX、PDF、PPTX、または XLSX の生成がオンになっている場合は、Compose を優先する必要があります。 PCで使用する場合でも、「悪意のない機種」をセキュリティ対策と考えないでください。

導入前のリソース計画

DeepTutor 自体は必ずしも大規模なモデルをネイティブに実行するわけではありませんが、ドキュメントの解析、埋め込み、ファイル生成、および同時タスクは依然としてリソースを消費します。事前に確認することをお勧めします。

添付ディレクトリがどのディスクに配置されるか。
アップロードされたファイルと生成されたファイルの保存期間。
ランナーが CPU、メモリ、プロセスの制限を設定するかどうか。
モデル API の同時実行性とコストの上限。
プロバイダーにリージョンとクォータの制限があるかどうかを検索します。
複数のユーザーの認証を有効にする必要があるかどうか。

ローカルモデルが接続されている場合、ビデオメモリとコンテキストの長さを個別に計算する必要があります。チャットに返信できるからといって、同じ構成で長い PDF、取得、ファイル生成が安定して実行できるわけではありません。

モデル構成の正しい順序

最初にメインのダイアログモデルを構成します

model_catalog.json または設定ページにプロバイダー、API アドレス、キー、モデル ID を追加します。最初に短い質問で接続をテストし、401、404、またはモデル名のエラーがないことを確認します。

埋め込みを再度設定する

ナレッジベースの検索にはベクトル化が必要です。埋め込みモデルとチャットモデルの 2 種類の構成があり、チャットが成功したからといってスキップすることはできません。埋め込みモデルを置き換えた後、古いインデックスを再構築する必要がある場合があります。そうしないと、ディメンションまたはセマンティックスペースが不一致になります。

最後に検索にアクセスします

外部検索は、クエリをサードパーティのサービスに送信します。まず、データがネットワークから離れることを許可するかどうかを明確にしてから、検索プロバイダーを構成します。内部ドキュメントを操作する場合は、外部検索をオフにして、アップロードされたマテリアルのみを使用することができます。

初回起動後の検証プロセス

検証1: 通常の会話

ツールを使わずに短い質問をして、モデルの戻り値とログを確認します。プロバイダー、機種ID、ネットワーク接続を確認することが目的です。

検証2: 情報に関する質疑応答

プライバシーのない短い PDF をアップロードし、テキスト内で直接答えが見つかる質問をし、ページ番号または根拠を尋ねます。回答が元のテキストと一致しない場合は、チャットモデルをすぐに変更するのではなく、解析、埋め込み、取得を確認してください。

検証 3: ファイルの生成

システムにヘッダーとテーブルのみを含むテスト DOCX を生成させ、ランナーログ、ダウンロードリンク、および出力ファイルを確認します。複雑な PPT や機密データを含むテーブルを初めて使用しないでください。

検証 4: リカバリの再開

コンテナーを再起動した後、設定、セッション、アップロードされたデータ、生成されたファイルがまだ存在しているかどうかを確認します。コンテンツが消えた場合、永続ボリュームは正しくマッピングされていません。

リバースプロキシと認証

LAN またはパブリックネットワークからアクセスする必要がある場合は、まず auth.json で認証を有効にしてから、HTTPS リバースプロキシを構成する必要があります。また、同期的にチェックします。

system.json のパブリック API アドレス;
CORS では、実際に使用されているドメイン名のみが許可されます。
Cookie のセキュリティ特性。
アップロードサイズとリクエストタイムアウト。
WebSocket またはストリーミング応答がプロキシによって正しく転送されるかどうか。・管理ページが外部に公開されているかどうか。

サービスを保護するために、推測しにくい URL だけに依存しないでください。パブリックネットワーク DeepTutor にはドキュメント、モデルキー、コード実行機能もあり、認定が最低要件です。

何をバックアップするか

少なくとも、data/user/settings/、ユーザープロファイル、セッションデータベース、生成された添付ファイルをバックアップします。 API キーは安全なキー管理を通じて再挿入でき、必ずしも通常のバックアップファイルに入れる必要はありません。

アップグレード前の推奨事項:

新しいタスクを停止します。
永続ディレクトリをバックアップします。
現在のイメージまたは送信されたバージョンを記録します。
構成の移行手順を読みます。
アップグレード後に 4 つの検証を再度実行します。

共通エラー比較表

現象	考えられる原因	トラブルシューティングの手順
ページは正常ですが、モデルが応答しません。キー、モデル ID、API ベースのエラー	プロバイダーのログと HTTP ステータスコード
チャットはできるが情報が乏しい Q&A	解析または埋め込みが構成されていません	文書テキスト、索引付けおよび検索結果
Office ファイルの生成に失敗しました	ランナー、依存関係、またはディレクトリのアクセス許可	サイドカーのログとマウントディレクトリ
再起動するとデータが消える	永続的なボリュームエラー	ボリュームとホストパスを構成する
リバースプロキシ後のストリーミング中断	バッファリング、タイムアウト、または WebSocket	プロキシ構成
CPU が引き続きフル状態です	タスク、ランナー、またはローカルモデルを解析する	コンテナリソースとプロセス一覧

よくある質問

ページは開けるがモデルが応答しない場合はどうすればよいですか?

まずプロバイダー、モデル ID、API アドレス、および model_catalog.json のキーが一致するかどうかを確認し、次にコンテナーログで 401、404、タイムアウト、またはコンテキスト長エラーを確認します。

DOCX または PDF の生成が失敗するのはなぜですか?

サンドボックスが閉じられていないことを確認し、Runnerが正常であるか、必要なPythonパッケージが存在するか、添付ディレクトリが書き込み可能であるかを確認してください。チャットのみが機能するが Office スキルが失敗する場合、通常はモデル接続に問題はありません。

複数の人が展開を共有できますか?

評価することは可能ですが、そのバージョンのユーザー分離機能を最初に確認する必要があります。モデルキー、アップロードされたデータ、セッション、生成されたファイルは、インターフェイスだけでは区別できません。検証する前にシングルユーザーサービスを使用する方が安全です。

ローカルモデルを使用してもデータは漏洩しませんか?

不確かな。外部検索、埋め込み、テレメトリ、およびリバースプロキシによっても、送信リクエストが生成される可能性があります。各プロバイダーの実際の所在はネットワークログを通じて確認します。

子プロセスを閉じた後、どの機能が影響を受けますか?

通常のチャットと実行不要の取得は引き続き機能しますが、Python 経由で Office、PDF などのファイルを生成する機能は影響を受けます。終了する前に、チームに本当に必要なスキルのリストを作成してください。

ランナーには他にどのような制限が必要ですか?

スタンドアロンのランナーはホストの子プロセスよりも安全ですが、コンテナ自体を構成する必要があります。

ルートファイルシステムを読み取り専用にするか、書き込み可能なディレクトリを最小限に抑えます。
非 root ユーザー。
Docker ソケットがマウントされていません。
ホストのホームディレクトリをマウントしないでください。
CPU、メモリ、プロセス数、実行時間を制限します。
外部ネットワークはデフォルトで禁止されているか、必要なターゲットのみが許可されています。
タスクごとに独立した一時ディレクトリを使用し、適時にクリーンアップします。
アップロードされたドキュメントと認証情報はログに出力されません。

ランナーがアプリケーションデータベース、モデルキー、またはホスト Docker にアクセスできる場合、その独立したコンテナーは分離の意味のほとんどを失います。

アップロードされたデータのライフサイクル

導入前に、ファイルがアップロードから削除までどこに行くのかを明確にする必要があります: ブラウザの一時キャッシュ、アプリケーションの添付ディレクトリ、解析結果、ベクトルインデックス、セッションレコード、生成されたファイル、バックアップ。ユーザーがインターフェイス上で元のファイルを削除した後、他のコピーが同時に削除されているかどうかもテストする必要があります。

内部データについては、明確な保存期間を設定し、バックアップと削除の戦略を運用保守文書に記述することをお勧めします。サービスがローカルにデプロイされているからといって、ログ、キャッシュ、スナップショット内のデータのコピーを無視することはできません。

オンラインにする前に最低限必要な承認フォーム

プロジェクト	合格基準
モデル	短い質問と回答と長いコンテキストの両方が利用可能
検索	正しいフラグメントとソースを返すことができます
ランナー	ファイル生成は別のコンテナーで実行されます。
永続性	データと構成は再起動後も引き続き存在します。
認証	ログインせずにデータとインターフェイスにアクセスできない
プロキシ	HTTPS、ストリーミング応答およびアップロード OK
バックアップ	別のテストインスタンスに復元する機能
削除	元のファイル、インデックス、生成された製品は、ポリシーに従ってクリーンアップされます。

これらのプロジェクトが検証されて初めて、長く使える現地展開が完成します。

概要

DeepTutor のデプロイメントの焦点は、「コンテナーを実行する」ことではなく、モデル構成、永続性、認証、およびコード実行境界を構成することです。個人利用の場合は、Docker Compose の独立した Runner も最初に使用し、ファイル生成が必要ない場合はホストのサブプロセスの実行を終了する必要があります。