tencent cloud

Cloud Log Service

ドキュメントCloud Log ServiceAgent可観測性アクセスガイドAI Agentの接続DeepSeek Harnessデータの接続

DeepSeek Harnessデータの接続

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-10-12 15:13:58
AI翻訳・品質チェック済み

操作シナリオ

DeepSeek Harness（以下、DSH）は、コーディングタスクの実行時に、セッション、推論ステップ、モデル呼び出し、ツール呼び出しなどの実行データを生成します。Tencent Cloud Agent可観測プラグインtencentcloud-agentobs-sdk-dshをインストールすることで、DSHのネイティブライフサイクルをAgent Traceデータに変換し、CLS（Cloud Log Service）に報告できます。
接続が完了すると、Tencent Cloud Agent可観測性で以下の情報を確認できます：
1回のタスクにおける完全な呼び出しチェーン、およびAgent、推論ステップ、モデル呼び出し、ツール呼び出しの間の親子関係。
各ステップの実行時間、モデル初回トークン遅延（TTFT）、入力Token、出力Token、キャッシュToken。
モデルとツール呼び出しの成功状態、失敗理由、再試行プロセス。
同一セッション内の複数ラウンドタスクの関連関係。
本文では以下の2つの接続方法を提供します。実際の状況に応じて選択できます：
アクセス方法
説明
推奨シナリオ
Skill対応のAIツールを使用し、AIが自動でログトピックを作成または再利用し、DSH環境を認識し、プラグインの接続と分析を完了します。
Skill対応のAIツールを使用し、ワンクリックで接続し、手動設定を減らすことを希望します。
手順に従ってDSHプラグインをインストールし、リージョンアクセスポイント、ログトピック、キーなどのパラメータを手動で入力して接続を完了します。
接続パラメータを細かく制御する必要がある場合、または使用するツールがSkillに対応していない場合です。

前提条件

接続を開始する前に、以下の準備作業が完了していることを確認してください：
CLSを有効にしました。
接続リージョン（Region）を確定しました。例えば広州リージョンはap-guangzhouです。方式1ではRegionを直接記入します。方式2では、該当リージョンに対応するCLS Endpointも取得する必要があります。
CLSログ書き込み権限を持つアクセス証明書を準備しました。CAMサブアカウント、CAM Role、または一時キーの使用を推奨します。TencentCloud APIキー情報はAPIキー管理で取得できます。
DSHがインストール済みであり、DSHのバージョンが>=0.1.0-rc.6 <0.2.0であることを確認しました。
プラグイン実行環境のNode.jsバージョンは18.0.0以降です。DSH自体のNode.jsバージョン要件は、インストールされているDSHバージョンの公式説明に従ってください。

方法1：Skillによるクイック接続と分析

Skill対応のAIツールを使用している場合は、Tencent Cloud Agent可観測性アクセスアシスタントを使用してアクセスと分析を自動的に完了できます。このSkillはアクセスと分析の機能を統合しており、ログトピックの自動作成または再利用、DSH環境の認識、プラグインのインストールと構成の完了が可能です。
AIツールに以下の内容を入力してください：
Tencent Cloud Agent可観測性アクセスSkillを使用してください：
https://skillhub.cn/skills/tencentcloud-cls-agent-obs

現在のDeepSeek HarnessをTencent Cloud Agent可観測性に接続してください。

アクセス方式：DeepSeek Harness
Region：ap-guangzhou

方法2：手動設定による接続

プラグイン、ログトピック、アクセス証明書などのパラメータをきめ細かく制御する必要がある場合、または使用するツールがSkillをサポートしていない場合は、以下の手順に従って手動でアクセスを完了してください。

ステップ1：Agent可観測アプリケーションの作成

手動でアクセスする前に、まずCLSコンソール > Agent可観測性にアクセスし、アプリケーションアクセスからアプリケーションを作成し、新しく作成したアプリケーションの右側にある編集をクリックし、そのログトピックIDをコピーしてください（以下のCLS_TOPIC_IDで使用します）。
説明：
Agent可観測性アプリケーションとTraceログトピックは同一リージョンに配置する必要があります。
プラグイン設定のCLS Endpointは、Traceログトピックが所在するリージョンと一致している必要があります。例えば、広州リージョンではap-guangzhou.cls.tencentcs.comを使用します。

ステップ2：DSHプラグインのインストール

DSHプラグインはProfileごとにインストールされます。実際に実行しているProfileに応じて対応するコマンドを実行してください。
web Profileを観測します：
dsh plugin --profile web add tencentcloud-agentobs-sdk-dsh
headless Profileを観測します：
dsh plugin --profile headless add tencentcloud-agentobs-sdk-dsh
harness Profileを観測します：
dsh plugin --profile harness add tencentcloud-agentobs-sdk-dsh

pnpmビルドスクリプトの問題

pnpm v9以降のバージョンでは、デフォルトで依存パッケージがinstallスクリプトを実行することを禁止する場合があります。ERR_PNPM_IGNORED_BUILDSが表示された場合は、対応するProfileディレクトリに移動して実行してください：
cd ~/.dsh/profiles/web
echo "enable-scripts=true" >> .npmrc
pnpm install
headlessまたはharness Profileの場合はディレクトリ名を置き換えてください。一度設定を完了すると、その後のインストールや更新では通常、繰り返し実行する必要はありません。
注意：
プラグインをインストールまたは更新した後、対応するDSHプロセスを再起動する必要があります。これにより、プラグイン設定が有効になります。

ステップ3：CLS接続情報の設定

プラグインは環境変数またはDSHプラグイン設定ファイルを通じて接続情報を提供できます。明示的なプラグイン設定は環境変数よりも優先されます。

方法1：環境変数の使用（推奨）

DSHを起動したのと同じターミナルで以下のコマンドを実行します：
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=<ログトピックID>
export CLS_SECRET_ID=<SecretId>
export CLS_SECRET_KEY=<SecretKey>
export CLS_SERVICE_NAME=dsh-agent
パラメータの説明は以下の通りです。
環境変数
必須/任意
説明
CLS_ENDPOINT
はい
CLSリージョン接続ポイントのドメイン名です。詳細はリージョンとアクセスドメインを参照してください。
広州リージョンを例にすると、外部ドメイン名：ap-guangzhou.cls.tencentyun.com、内部ドメイン名：ap-guangzhou.cls.tencentcs.comです。
CLS_TOPIC_ID
はい
手順1で取得したログトピックIDです。
CLS_SECRET_ID
はい
Tencent Cloudアクセス認証情報SecretIdです。APIキー管理にアクセスして取得できます。
CLS_SECRET_KEY
はい
Tencent Cloudアクセス認証情報SecretKeyです。APIキー管理にアクセスして取得できます。
CLS_SERVICE_NAME
いいえ
サービス名です。CLS内で異なるDSHインスタンスまたは業務を区別するために使用します。デフォルト値はdeepseek-harnessです。

方法2：プラグイン設定ファイルの使用

$DSH_HOME/profiles/<profile>/cordis.patch.ymlを編集します。DSH_HOMEが設定されていない場合、デフォルトのパスは通常~/.dsh/profiles/<profile>/cordis.patch.ymlです。
プラグイン設定に以下の内容を追加します：
- id: cls-observability
  config:
    enabled: true
    endpoint: ap-guangzhou.cls.tencentcs.com
    topicId: <TraceログトピックID>
    secretId: <SecretId>
    secretKey: <SecretKey>
    serviceName: dsh-agent
    captureContent: true
    batchMaxSize: 32
    flushIntervalMs: 5000
    debug: false
警告：
アクセス証明書は機密情報に属します。環境変数またはキー管理ツールを通じて注入することを優先し、実際のSecretIdとSecretKeyをコードリポジトリにコミットしないでください。

ステップ4：DSHを起動し、テストTraceを生成する

web Profileを例に、以下のコマンドを実行してDSHを起動します：
dsh --profile web
起動完了後、DSHでテストタスクを1回実行します。テストタスクは少なくとも1回のモデル呼び出しをトリガーすることを推奨します。ツールSpanも同時に検証する必要がある場合は、ファイル読み取り、コマンド実行、またはその他のツール呼び出しをトリガーする、機密情報を含まないテストタスクを使用できます。
プラグインの読み込みが成功すると、DSHログに以下の情報が表示されます：
[cls-dsh] loaded; endpoint=<CLS Endpoint>; topic=<Topic ID プレフィックス>...; content=enabled
設定が不完全な場合、プラグインはログに不足している設定項目を一覧表示し、収集を停止します。ただし、DSH自体の起動には影響しません。

ステップ5：報告結果の検証

テストタスクの完了後、1回の更新サイクルを待ちます。デフォルトの更新間隔は5秒です。

Agent可観測性での検証

1. CLSコンソール > Agent可観測性にログインします。
2. 手順1で作成したアプリケーションに入ります。
3. 最新のTraceを表示し、呼び出しツリーに以下のSpanタイプが含まれていることを確認します：
ENTRY：1回のリクエストがDSHに入ります。
AGENT：Agentの実行プロセス。
STEP：1回のReAct推論ステップ。
CHAT：1回の実際のモデル呼び出し。
TOOL：1回のツール呼び出し。
4. CHAT Spanを選択し、モデル名、所要時間、TTFT、Token使用量、ステータス情報を確認できます。
5. TOOL Spanを選択し、ツール名、呼び出し所要時間、実行ステータスを確認できます。

検索分析での検証

Traceログトピックの検索分析ページに移動し、以下のステートメントを実行して最新データを照会することもできます：
* | SELECT traceID, spanID, parentSpanID, spanKind, name, durationMs, statusCode
    ORDER BY __TIMESTAMP__ DESC
    LIMIT 50
指定したTraceを照会します：
traceID:"<Trace ID>"
同一Traceで複数のSpanを照会でき、かつparentSpanIDが対応する親Spanに関連付けられる場合、Traceデータが正常に報告されたことを示します。

一般的な操作

コンテンツ収集の無効化

デフォルトでは、プラグインはプロンプト、モデル応答、ツールパラメータ、ツール結果をSpanに書き込みます。ソースコード、認証情報、個人データを含む環境では、コンテンツ収集を無効にし、呼び出し構造、所要時間、ステータス、Token使用量のみを保持することをお勧めします。
環境変数で無効にします：
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false
プラグイン設定で無効にします：
- id: cls-observability
  config:
    captureContent: false
説明：
明示的なプラグイン設定は環境変数よりも優先されます。

プラグインの更新

以下のコマンドを実行して、対応するProfileにインストール済みのプラグインを更新します：
dsh plugin --profile web update
headlessまたはharness Profileの場合は、--profileパラメータを置き換えてください。更新が完了したら、対応するDSHプロセスを再起動してください。

プラグインのアンインストール

インストール済みプラグインのProfileのみをアンインストールします。実際にインストールされているProfileに基づいて以下のコマンドを実行します：
dsh plugin --profile web remove tencentcloud-agentobs-sdk-dsh
dsh plugin --profile headless remove tencentcloud-agentobs-sdk-dsh
dsh plugin --profile harness remove tencentcloud-agentobs-sdk-dsh

関連説明

設定項目の説明

設定項目
デフォルト値
説明
enabled
true
収集を有効にするかどうかを指定します。falseに設定した場合、プラグインをアンインストールすることなく収集を停止できます。
endpoint
CLS_ENDPOINT
CLS APIアクセスポイントです。
topicId
CLS_TOPIC_ID
TraceログトピックID。
secretId
CLS_SECRET_ID
Tencent Cloudアクセス認証情報SecretId。
secretKey
CLS_SECRET_KEY
Tencent Cloudアクセス認証情報SecretKey。
serviceName
deepseek-harness
サービス名です。
resourceAttributes
{}
Spanに書き込むカスタムリソース属性で、キーと値はどちらも文字列です。
captureContent
true
プロンプト、モデル応答、ツールパラメータ、ツール結果を収集するかどうかを指定します。
contentMaxChars
128000
単一コンテンツ属性に保持される最大文字数です。超過分は切り捨てられます。
batchMaxSize
32
1回のバッチで報告する最大Span数です。
maxQueueSize
2048
メモリキューに保持できる最大Span数です。上限を超えた場合、プラグインは最も古いデータの一部を破棄し、DSHのブロックを回避します。
flushIntervalMs
5000
定時リフレッシュ間隔です。単位はミリ秒です。
retryTimes
3
CLS SDKのリクエスト再試行回数です。
debug
false
プラグインのデバッグログを出力するかどうかです。

Span構造の説明

プラグインは1回のDSH Turnを1つのTraceとして扱い、sessionIDを通じて同一セッション内の複数ラウンドのTraceを関連付けます。
ENTRY
└── AGENT
    └── STEP
        ├── CHAT
        └── TOOL
Spanタイプ
名前形式
説明
ENTRY
enter_application
1回のリクエストがDSHに入り、現在のTraceのルートSpanです。
AGENT
invoke_agent {agentName}
Agentの実行プロセスであり、このターンのモデル、Token、終了状態を集約します。
STEP
react round_{step}
1回のReAct推論ステップです。
CHAT
chat {model}
1回の実際のモデル呼び出しです。モデルの再試行では新しいCHAT Spanが生成され、前回のSpanとは統合されません。
TOOL
execute_tool {toolName}
1回のツール呼び出しであり、ツール名、呼び出しID、所要時間、状態が含まれます。
説明：
DSH内部でコンテキスト圧縮とセッションタイトル生成に使用されるモデル呼び出しは、CHAT Spanを生成しません。これにより、フレームワーク内部の呼び出しがビジネス側のモデル呼び出し統計に影響を与えることを防ぎます。

よくあるご質問

プラグインはインストール済みですが、CLSにトレースデータがありません

以下の順序で確認してください：
1. プラグインが現在実行中のProfileにインストールされていることを確認します。
2. インストールまたは設定変更後、DSHプロセスを再起動したことを確認してください。
3. DSHログを確認し、[cls-dsh] loaded情報が存在し、設定欠落のプロンプトがないことを確認してください。
4. CLS_ENDPOINTがTraceログトピックと同じリージョンに存在することを確認してください。
5. CLS_TOPIC_IDがAgent可観測性アプリケーションIDではなく、ログトピックIDであることを確認してください。
6. アクセスキーが対象ログトピックにデータを書き込む権限を持っていることを確認してください。
7. 現在の環境が設定されたCLS Endpointにアクセスできることを確認してください。
8. テストタスクの完了後、少なくとも1回の更新サイクルを待ってからデータを照会してください。
プラグインの詳細な実行情報を確認する必要がある場合は、一時的にdebug: trueを設定し、DSHを再起動した後、[cls-dsh]で始まるログを確認できます。

トレースにプロンプト、応答、ツールパラメータがありません

以下の設定を確認してください：
プラグイン設定のcaptureContentがfalseに設定されているかどうかを確認してください。
環境変数OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTがfalse、no、off、disabled、または0に設定されているかどうかを確認してください。
コンテンツ収集を無効にしても、呼び出しツリー、所要時間、ステータス、Token使用量の報告には影響しません。

同一DSHタスクに類似したトレースが2件存在する

複数のDSH Trace報告経路が同時に有効になっていないか確認してください。例えば、CLS DSHプラグインと他のコレクターまたはOTLPプラグインが同時に有効になっており、データを同じログトピックに送信している場合です。对照検証の場合を除き、同じDSHインスタンスにはTrace報告経路を1つだけ保持することを推奨します。

一部のDSH内部モデル呼び出しがトレースに表示されない

これは想定された動作です。プラグインはコンテキスト圧縮（compaction）とセッションタイトル生成（session title）に使用される内部モデル呼び出しを無視し、実際のタスク実行中のモデル呼び出しのみを収集します。

前の記事へ: AI Coding Agentデータの取り込み（Onesuite-Pilot）次の記事へ: Onesuite-Pilot バージョン情報

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック

キーワードで検索
    Enter keywords to search documentation