管理者ヘルプ

はじめに

組織管理画面（/company）では、社内文書の登録・公開、スタッフの招待、AI への参照権限の設定を行います。

初めての方は、まず下の 最速チュートリアル で「PDF を1つ登録 → ポータルで質問」まで通してください。サイドバー下部の「ポータルへ」から、管理者自身も AI チャットを試せます。

最速チュートリアル（サインアップ〜最初の回答）

サインアップ直後にやるべきことを、最短ルートで案内します。ゴールは「サンプル PDF を登録 → ポータルで質問して根拠付きの回答を得る」です。サンプル PDF は とうもろこしの栽培方法.pdf を使います（右クリック保存でも可）。

Step 1 — 新規登録（サインアップ）

1. /signup を開きます。
2. 組織名・管理者名・メール・パスワード（8文字以上）を入力し、「無料トライアルを開始する」をクリックします。トライアル期間は登録から 30日間 です。
3. 成功すると組織管理画面（ダッシュボード）に入ります。

Step 2 — LLM が選べることを確認（任意だが推奨）

1. サイドバーの「LLM設定」を開きます。
2. 利用可能なモデルが一覧にあれば、組織で使うモデルを選択して保存します。

Step 3 — サンプル PDF を文書登録する

1. サイドバーの「文書管理」を開きます（/company/documents）。
2. 画面上部のドロップゾーンに とうもろこしの栽培方法.pdf をドラッグ＆ドロップします。
   または「文書を作成」からタイトルを付けて保存し、続けて PDF をアップロードします。
3. 一括ドロップの場合はキューに並ぶので、「一括登録を開始」などでアップロードを完了させます。
4. 一覧に「とうもろこしの栽培方法」が表示されれば OK です。初期状態は多くの場合「下書き」です。

Step 4 — 公開してベクター化する（最重要）

ポータルの AI は、公開済みかつベクター化済み の文書だけを検索します。ここを飛ばすと「情報を見つけることができませんでした」になります。

1. 一覧で対象文書の行をクリックして詳細を開くか、一覧の地球アイコンから「公開」します。
2. ステータスが「公開中」になったことを確認します。
3. 「ベクター化」を実行します（詳細画面のボタン、または一覧の一括操作）。
4. 一覧の「ベクター」列が 済 になるまで待ちます（処理中 → 済）。

Step 5 — ポータルへ移って質問する

1. サイドバー下部の「ポータルへ」をクリックします（または /portal）。
2. 「新しい会話」を開始します。
3. 例: とうもろこしの種まきの時期はいつですか？ と入力し、⌘+Enter（Windows は Ctrl+Enter）または送信ボタンで送ります。
4. 回答の下に「参照した文書」が出れば成功です。サンプルなら「とうもろこしの栽培方法」が根拠として付きます。

チェックリスト（ここまでできれば完了）

• 組織アカウントでログインできる
• 文書一覧にサンプル PDF がある
• ステータスが「公開中」
• ベクターが「済」
• ポータルで質問し、参照文書付きの回答が返る

陥りやすいミスまとめ

ダッシュボード

組織の利用状況をひと目で確認できます。

• 総文書数 — 公開中 / 下書きの件数
• ストレージ使用量 — アップロード済みファイルの合計サイズ
• ユーザー数 — 登録スタッフとアクセスグループ数
• ベクター化済み — AI 検索可能な文書数と未処理件数

下段の大カードには ストレージ使用状況・最近の文書・質問数 が並びます。質問数カードには 👍 / 👎 のフィードバック累計も表示されます。

組織管理者向けには 今週のナレッジギャップ カードも表示されます。質問シグナル／未参照文書／賞味期限切れ回答／根拠衝突の件数と、直近7日のナレッジの状態（良好・経過観察・要注意）が表示されます。詳細は ナレッジギャップ ページへ移動できます。

最近追加・更新された文書へのショートカットも表示されます。

文書管理

/company/documents で PDF 等の文書を一覧・登録・公開します。

新規文書の登録

1. 「新規文書」をクリック
2. PDF ファイルをドラッグ＆ドロップまたは選択
3. タイトル、カテゴリ（任意）、アクセスグループ（任意）を設定
4. 保存 — 初期状態は「下書き」

公開とベクター化

文書を 公開 すると、テキスト抽出とベクター化ジョブがキューに入ります。一覧の「ベクター化」列で進捗を確認できます。

参照回数

文書一覧の「参照回数」列に、RAG 回答でその文書が参照された累計回数が表示されます。よく使われている文書・一度も使われていない文書を把握し、文書整理の判断に活用できます。

一括操作

チェックボックスで複数文書を選択し、一括公開・非公開・削除が可能です。

文書詳細

文書名をクリックすると詳細画面が開きます。バージョン管理、PDF プレビュー、手動ベクター化の再実行ができます。

• 新バージョンのアップロード — 改訂 PDF を追加すると旧版は履歴に残る
• ベクター化を再実行 — 失敗時や内容更新後に使用
• 公開 / 非公開 — 非公開にすると AI は参照しない

カテゴリ管理

文書を分類するためのカテゴリを作成・編集します。ポータルや管理画面でのフィルタリングに利用されます。

アクセスグループ

スタッフの所属グループごとに、参照可能な文書を制限します。機密文書を特定部署だけに公開する場合に使用します。

1. アクセスグループを作成（例: 「設備管理課」「営業部」）
2. ユーザー管理でスタッフをグループに所属させる
3. 文書管理で各文書にアクセスグループを割り当てる

ユーザー管理

スタッフや文書管理者を招待します。組織管理者のみがアクセスできます。

LLM 設定

ポータルの AI 回答に使用する LLM モデルを選択します。956 Inc. が提供するモデル一覧から選べます。

プラン・お支払い

トライアルは登録から 30日間 です。終了後は有料プランへのアップグレードと Stripe による決済を行います。期限切れ後にログインすると /trial_expired.html から直接契約できます。

• スモール — ¥12,800 / 月（ユーザー無制限・PDF200・10GB・質問500・同時2）
• ミディアム — ¥39,800 / 月（ユーザー無制限・PDF1,000・30GB・質問5,000・同時5）
• ラージ — ¥89,800 / 月（ユーザー無制限・PDF5,000・100GB・質問10,000・同時10）
• エンタープライズ — 要お問い合わせ（無制限・専用環境/SLA/SSO 等）

質問数・ストレージが足りないときは、プランを上げずに「プラン・お支払い」から追加パックを購入できます。質問は当月分の一回払い（繰越なし）、ストレージは月額で何度でも追加できます。

質問分析

/company/question-analytics で、ユーザーが実際に投げた質問を AI がクラスタリングし、よく聞かれるテーマを頻度順に可視化します。

• 質問パターン数 — 意味的に近い質問をまとめたクラスター数
• 総質問数 — 累計の質問件数
• 回答できなかった質問 — 「わかりません」「見つかりません」などのパターンで返答したクラスター数
• フィードバック — 👍 / 👎 の累計数

フィルター

FAQ への追加

クラスターの「FAQ追加」ボタンを押すと、質問文（編集可）・AI の回答候補・アクセスグループを設定して FAQ に登録できます。AI の回答候補はそのまま使うか、自由に編集して利用します。

モーダル内の AIで下書き を押すと、現在のナレッジベースから回答文を再生成できます。ギャップ埋めや候補が弱いときのたたき台に使えます（詳細は ナレッジギャップ）。

ナレッジギャップ

/company/knowledge-gaps で、弱い／嫌われている質問パターン・未参照文書・根拠衝突を一覧し、FAQ 化やアーカイブ候補への移動まで進めます。組織管理者のみ利用できます。

ナレッジの状態

ページ上部に直近7日の健康状態が表示されます。

• 良好 / 経過観察 / 要注意 — ギャップ・👎・賞味期限切れ・根拠衝突の量から判定
• 指標 — 質問数、未回答、👍👎、賞味期限切れ回答、根拠衝突件数

サマリー

• 質問ギャップ — 直近7日で、👎がある、または根拠が弱い／答えられなかった質問パターンの件数
• 未参照の文書 — 公開・ベクター化済みで、参照回数が 0 の文書件数（期間制限なし）

質問ギャップ（重要度順）

直近7日の質問をクラスタリングし、次のいずれかに当てはまるパターンを重要度順に表示します。

• 👎（役に立たなかった）フィードバックがついている
• 根拠が弱い、または「わかりません」などの未回答パターンで返答している

各行には質問の代表文・件数・最終質問日・関連文書へのリンクが表示されます。「FAQ追加」から FAQ 登録画面を開けます。

AIで下書き（Gap → Draft）

FAQ 追加モーダルの AIで下書き ボタンで、管理者権限（全文書参照）の RAG から回答文を生成できます。既存の回答候補が弱い・空のときにたたき台として使えます。生成後は必ず内容を確認・編集してから登録してください。

使われていない文書

公開かつベクター化済みで、AI 回答の根拠として一度も参照されていない文書を一覧します。

• 詳細 — 文書詳細ページを開き、内容・アクセスグループ・公開状態を確認
• アーカイブ候補 — 不要と判断した文書をゴミ箱へ移動（あとから復元可能）

根拠の衝突

1つの回答が複数文書を参照したとき、文書間で内容が食い違う可能性がある場合に検出します（例: 「必須」と「不要」、日数の不一致）。

• 本ページに直近7日の衝突付き回答が一覧表示されます
• ポータルの該当回答にも警告が表示されます
• ヒューリスティック検知のため誤検知があり得ます。必ず原本で最終確認してください

誰に見える？（権限プレビュー）

/company/who-sees-what で、同じ質問をアクセスグループごとの権限で並列に RAG 回答します。組織管理者のみ利用できます。

1. 比較したい質問を入力する
2. 視点を選ぶ（管理者／グループ未所属／アクセスグループ最大4）
3. 「権限別に比較」を押す
4. 各カードの回答文・参照文書数・参照抜粋を見比べる

• 管理者（全文書） — 権限制限なしの回答（ベースライン）
• グループ未所属 — アクセスグループ未設定の文書だけが見えるスタッフ視点
• アクセスグループ — そのグループに紐づく文書＋共通文書が見える視点

FAQ 管理

/company/faqs で、ポータルの「よくある質問」ページに表示する FAQ を管理します。

• 表示順の変更 — ▲ / ▼ ボタンで並び替え
• 表示 / 非表示 — 目のアイコンで個別に公開・非公開
• 編集 — 質問文・回答を後から変更可能
• 削除 — FAQ の完全削除

アクセスグループとの連携

FAQ にアクセスグループを設定すると、そのグループに所属するユーザーのみポータルで表示されます。未設定の場合は全スタッフに表示されます。

設定

組織名、ポータル用ログイン URL、テーマなどを管理します。

ポータルキー URL

/portal/login/{キー} 形式の URL をスタッフに共有すると、メール・パスワードなしでポータルにログインできます。キーは設定画面から再生成可能です。

外部 RAG API（OpenAPI）

自社アプリ、n8n、Cursor / OpenClaw などのエージェントから、組織の公開済み PDF に根拠付きで質問するための Web API です。人が仕様を読むほか、チートシートを AI エージェントに渡してコードや運用手順を書かせる使い方も想定しています。

ブラウザのログイン API（/api/v1/company や /api/v1/portal）は公開対象ではありません。

AI Agent チートシート

下の契約（チートシート）をコピーしてエージェントに渡し、「やりたいこと」を自然文で依頼します。キー文字列は含めないでください。

1. チートシートをコピーアコーディオンを開き「コピー」で全文を取得します（または /llms-api.txt）。
2. エージェントに読み込ませるCursor / OpenClaw 系などのルール・プロンプト・会話に貼ります。
3. やりたいことを伝える例: 「社内PDFに質問する Python を書いて」「根拠 PDF を開く curl を」。
4. キーは見せない環境変数 SPARKLE_SECURITY_KEY で渡し、チャット・ログ・コミットに平文キーを出さない。

# Sparkle External RAG API — LLM / Agent cheat sheet
Base: https://sparkle.956.jp
Auth: Authorization: Bearer <SPARKLE_SECURITY_KEY>
      or X-Sparkle-Security-Key: <SPARKLE_SECURITY_KEY>
Actor: X-Employee-Code: <employee_code>
OpenAPI: https://sparkle.956.jp/openapi.yaml
Help: https://sparkle.956.jp/help_admin.html#external-api

Hard rules:
- Call ONLY /api/v1/external/*
- Never use /api/v1/company/* /portal/* /auth/*
- Never print/commit/share the key
- Always send X-Employee-Code (that user's access groups)
- Each successful query counts toward monthly questions
- Timeout >= 60s (LLM generation)

Endpoints:
POST /api/v1/external/rag/query
GET  /api/v1/external/documents/{id}/preview

curl:
export SPARKLE_SECURITY_KEY=…
curl -sS -X POST "https://sparkle.956.jp/api/v1/external/rag/query" \
  -H "Authorization: Bearer $SPARKLE_SECURITY_KEY" \
  -H "X-Employee-Code: $SPARKLE_EMPLOYEE_CODE" \
  -H "Content-Type: application/json" \
  -d '{"question":"有給休暇の日数は？","include_sources":true}'

Playbooks:
- Ask: POST rag/query with question + include_sources true
- Follow-up: same + history[{role,content}]
- Open source PDF: GET documents/{document_id}/preview
- Health: POST rag/query with a short question → expect 200 (uses 1 quota)

Errors: 401 unauthorized|actor_required|actor_unknown|actor_inactive · 403 company_inactive|chat_blocked · 422 question_blank|question_limit · 429 rate_limited · 502 llm_unavailable

やりたいこと一覧

できること（提供中）と、今後の予定を一覧にしています。項目を選ぶと呼び出し方までジャンプします。

接続の基本

ベースURL: https://sparkle.956.jp

認証: Authorization: Bearer … または X-Sparkle-Security-Key（組織のセキュリティーキー。平文は発行時に一度だけ表示）。あわせて X-Employee-Code（ユーザーの社員番号）を送る。

1. キーを依頼するスーパー管理者が組織詳細の「外部連携セキュリティーキー」で発行します。組織管理者画面からは発行できません。956 の担当者へ依頼してください。
2. 安全な場所に保存する環境変数 SPARKLE_SECURITY_KEY に入れる。平文はチャットや git に出さない。
3. ヘッダを付けるリクエストに Bearer（または X-Sparkle-Security-Key）と、対象ユーザーの X-Employee-Code を付ける。社員番号は組織のユーザー編集で Usher の社員番号と一致させておく。

社内PDFに質問して根拠付きで答える 提供中

こんなときに — 社内ポータル以外のアプリやボットから、公開済みマニュアルに質問したい。

POST /api/v1/external/rag/query
Authorization: Bearer $SPARKLE_SECURITY_KEY
X-Employee-Code: $SPARKLE_EMPLOYEE_CODE
Content-Type: application/json

{"question":"有給休暇の日数は？","include_sources":true}

会話履歴を付けて続きを聞く 提供中

こんなときに — 「それは何日まで繰り越せる？」のように、直前のやり取りを前提にしたい。

POST /api/v1/external/rag/query
{"question":"それは何日まで繰り越せる？","include_sources":true,"history":[{"role":"user","content":"有給は何日？"},{"role":"assistant","content":"年次有給は…"}]}

根拠になったPDFを開く 提供中

こんなときに — 回答の出典 PDF をそのまま見せたい。

GET /api/v1/external/documents/{document_id}/preview
Authorization: Bearer $SPARKLE_SECURITY_KEY
X-Employee-Code: $SPARKLE_EMPLOYEE_CODE

連携の疎通確認をする 提供中

こんなときに — キーと LLM が通るか、デプロイ後に一度だけ確かめたい。

キーの自己発行・PDFアップロード 予定

こんなときに — 組織管理者が自分でキーを回したい、アップロードも API にしたい。

よくある質問

ポータル

サイドバー下部の「ポータルへ」から、/portal の AI チャット画面に移れます。スタッフと同じ画面で、公開・ベクター化済みの文書に対する回答を試せます。

• 新しい会話 — 左サイドバーまたはメインのボタンから開始
• 会話履歴 — 過去の質問が一覧表示され、クリックで再開
• 今月の質問数 — サイドバー下部にプラン枠に対する利用状況を表示

質問と参照元

1. 入力欄に質問を書き、⌘+Enter（Windows は Ctrl+Enter）または送信ボタンで送る
2. 回答の下の「参照した文書」で根拠 PDF を「表示」「DL」できる
3. 👍 / 👎 で回答品質を評価する（ダッシュボード・質問分析に集計される）

回答の信頼性に関する警告

• 更新あり（回答の賞味期限） — 回答作成後に参照文書が再ベクター化された場合に表示。内容が古くなっている可能性があります
• 根拠に衝突の可能性 — 参照した複数文書の間で、必須／不要や日数などが食い違う可能性がある場合に表示

よくある質問（ポータル側）

サイドバーの「よくある質問」から閲覧できます。内容の追加・並び替えは管理画面の FAQ管理 で行います。