process-faq

Process FAQ - FAQ ナレッジベースプロセッサー

生の FAQ ドキュメントを、インテリジェントなコンテンツ拡張と分析によって RAG に最適化された構造化フォーマットに変換します。

このスキルの機能

このスキルは次のことを支援します:

1. FAQ ドキュメントを変換して読みやすい Markdown フォーマットにする (スクリプト)
2. FAQ コンテンツを分析し、拡張の機会を特定する (Claude)
3. コンテンツを拡張する: 複雑な質問を分割し、回答を書き直す (Claude)
4. フォーマットを標準化し、キーワードを自動生成する (スクリプト)

対応入力フォーマット

• Excel (.xlsx)
• Word (.docx)
• PDF (.pdf)
• テキスト (.txt)

ワークフローの概要 (3 ステップのプロセス)

Step 1: Convert → Markdown (script)
Step 2: Expand → Enhanced FAQ (Claude - THIS IS THE KEY STEP!)
Step 3: Standardize → Final RAG format (script)

新しいワークフロー (Claude + スクリプトの連携)

ステップ 1: Markdown に変換する (スクリプト)

まず、Claude が読み取って分析できるように、入力ファイルを Markdown に変換します:

python process-faq/scripts/convert_to_markdown.py <input_file>

これにより、構造化された FAQ コンテンツを含む *_for_analysis.md ファイルが作成されます。

なぜ Markdown なのか?

• Claude がコンテンツを直接読み取って理解できる
• 単にフォーマットを確認するだけでなく、コンテンツの品質を分析するのに適している
• きめ細かくインテリジェントな分析が可能になる

ステップ 2: Claude がコンテンツを分析して拡張する (重要!)

ここが YOU (Claude) が価値を生み出す最も重要なステップです!

Markdown ファイルを読み込み、深いコンテンツ分析と拡張を実行します:

フェーズ A: コンテンツ品質分析 (质量检查)

重要: コンテンツを拡張する前にこれを行ってください!

問題を特定して記録します:

1. 論理的な問題 (逻辑问题)

   • 矛盾: 異なる回答が相反する情報を示していませんか?
     • 例: Q1 では「支持退货」と書かれているのに、Q2 では「不支持退货」と書かれている
   • 不整合: 類似した質問に対して異なる回答がありませんか?
     • 例: 「配送时间 3 天」と「配送时间 5-7 天」
   • 古い情報: 旧製品、価格、ポリシーへの言及がありませんか?

2. 重複/冗長なコンテンツ (重复内容)

   • 完全な重複: 同じ質問が複数回登場する
   • 意味的な重複: 「如何登录?」と「怎么登录?」(同じ意味)
   • 回答の重複: 複数の質問が 80% 以上同一のコンテンツを共有している

3. 欠落または不完全な情報 (缺失信息)

   • 不完全な回答: 簡潔すぎる、重要な手順や詳細が欠けている
   • コンテキストの欠落: ユーザーが持っていないかもしれない知識を前提としている
   • 論理の破綻: 回答が実際には質問に答えていない

4. 明確さの問題 (表达问题)

   • 不明確な質問: 曖昧すぎる (「支持什么?」)
   • 曖昧な用語: 定義されていない専門用語や略語
   • 悪い構造: フォーマットのない長文の塊

必要な対応: 見つかったすべての問題を記録し、次のように判断します:

• ✅ 修正: 矛盾を解決し、重複を統合し、曖昧さを明確にする
• ⚠️ フラグ: ユーザーによる確認が必要な問題を記録する
• ❌ 削除: 本当に無用または不正確なコンテンツを削除する

フェーズ B: コンテンツ拡張戦略

目標: 小規模な FAQ を、包括的で高品質なナレッジベースに変換する

重要: 拡張は品質分析の後に行う必要があります!

主な拡張テクニック:

1. まず問題を解決する (フェーズ A の検出結果に基づく)

   • 矛盾を修正: 正しい情報を選択し、ユーザーに不確実性を明記する
   • 重複を統合: 意味的に同一の質問を最適な 1 つのバージョンに統合する
   • 不完全を補完: 不足している手順を補い、コンテキストを追加する
   • 曖昧さを明確化: 曖昧な質問を具体的に言い換える

2. 複雑な質問を分割する

   • 「如何使用产品?」のような 1 つの質問に複数のサブトピックが含まれる場合
   • 具体的な質問に分割します: 「如何安装?」「如何配置?」「如何维护?」

3. 長い回答からナレッジポイントを抽出する

   • 1 つの回答が 500 文字以上で複数のトピックを扱っている場合
   • それぞれの異なるナレッジポイントを特定する
   • 各ポイント専用の Q&A を作成する
   • ただし: 抽出した各ポイントが正確で一貫していることを確認する

4. 不足している一般的な質問を特定する

   • ドメインに基づいて、ユーザーが自然に尋ねるであろうことは何か?
   • 存在すべきなのに存在しない質問を追加する
   • ユーザージャーニーを考慮する: 購入前 → 購入 → 使用 → トラブルシューティング

5. 明確さのために回答を書き直す

   • 各回答を簡潔かつ焦点を絞ったものにする
   • 適切でない場合はセールス的な表現を削除する
   • 構造を追加する (番号付きリスト、箇条書き)
   • 他の関連する回答との一貫性を確保する

例: 品質分析 + 拡張

元の内容 (問題あり):

Q1: 你们是怎么调理睡眠的?
A1: [500字，包含：产品介绍、使用流程、手环说明、"手环180元"、售后政策等]

Q2: 先用后付是什么意思?
A2: [与Q1相同的500字回答]

Q3: 华为手环多少钱？
A3: 手环200元左右

フェーズ A の分析 - 検出された問題:

• ❌ 矛盾: Q1 は「手环 180 元」と述べ、Q3 は「手环 200 元左右」と述べている
• ❌ 重複: Q1 と Q2 の回答が完全に同じ
• ⚠️ 重複範囲: 3 つの質問すべてが手环に言及しており、情報が散在している

フェーズ B の拡張 - 修正後:

Q1: 你们是怎么调理睡眠的？
A1: 我们通过太赫兹能量睡垫来调理睡眠，能帮助疏通经络、改善气血循环...
[简洁，只讲核心调理原理，不再包含价格等无关信息]

Q2: 先用后付是什么意思？
A2: 先用后付就是您可以先把产品拿回家免费体验，有效果再付款...
[独立回答，不再重复Q1的内容]

Q3: 华为手环多少钱？
A3: 华为手环180元左右（已统一价格，解决矛盾）

Q4: 为什么要用华为手环测睡眠？
A4: 手环能精准测出入睡时间、深睡时长等数据...
[新增问题，补充手环相关信息]

Q5: 手环怎么使用？
A5: 充电后戴在手腕上，连接手机APP即可...
[新增问题，完善手环知识点]

まとめ:

• 1 件の矛盾を修正 (価格の統一)
• 1 件の重複を統合 (Q1 と Q2)
• 3 → 5 件の FAQ に拡張 (ナレッジポイントの抽出)
• 各回答が焦点を絞った一貫性のある内容に

フェーズ C: カテゴリ分類

明確なカテゴリ構造を設計します:

• 関連する質問をまとめてグループ化する
• ドメインに適したカテゴリ名を使用する
• 主要カテゴリを 5〜10 個を目安にする

ステップ 3: ユーザーへの確認 (任意)

以下の点について明確化が必要な場合は、AskUserQuestion ツールを使用してください:

• ドメイン固有の用語
• トーンの好み (フォーマル vs カジュアル)
• セールス的な表現を残すかどうか
• 優先的に拡張するトピック

ほとんどの場合、分析に基づいてステップ 4 に直接進んでかまいません。

ステップ 4: 拡張済み FAQ の生成 (Excel)

重要: ここで実際のコンテンツ拡張を行います!

拡張済みの FAQ コンテンツを含む新しい Excel ファイルを作成します:

ファイル命名: <original_name>_expanded.xlsx

必須列:

• 分类 (カテゴリ)
• 问题 (質問)
• 回答 (回答)

任意列 (存在しない場合、スクリプトが生成します):

• 关键词 (キーワード) - 空のままにしておいてかまいません。スクリプトが自動生成します

ファイルの作成方法:

重要 (クロスプラットフォーム互換性):

• python -c "..." を使ってインラインの Python コードを実行しないでください - Windows ではクォートのエスケープ問題が発生します
• 必ず Write ツールを使って .py スクリプトファイルを先に作成し、その後 python script.py で実行してください

手順:

1. まず、Write ツールを使って Python スクリプト (例: create_faq.py) を作成します:

# create_faq.py - Use Write tool to create this file
import pandas as pd

data = [
    {
        "分类": "睡眠问题咨询",
        "问题": "你们是怎么调理睡眠的？",
        "回答": "我们通过太赫兹能量睡垫来调理睡眠..."
    },
    {
        "分类": "睡眠问题咨询",
        "问题": "我总是入睡困难怎么办？",
        "回答": "入睡困难通常和气血不畅有关..."
    },
    # ... 添加所有扩展后的FAQ
]

df = pd.DataFrame(data)
df.to_excel("filename_expanded.xlsx", index=False)
print("Successfully created filename_expanded.xlsx")

2. 次に Bash を使ってスクリプトを実行します:

python create_faq.py

3. 使用後に一時スクリプトを削除します:

rm create_faq.py  # or 'del create_faq.py' on Windows CMD

保存前の品質チェックリスト:

• 各質問が具体的で焦点が絞られている
• 各回答が簡潔である (通常 50〜200 文字)
• 質問が論理的なカテゴリごとにグループ化されている
• すべての重要なナレッジポイントが網羅されている
• 冗長または重複した質問がない

ステップ 5: スクリプトによるフォーマットの標準化

スクリプトを使用して拡張済みファイルを処理します:

python process-faq/scripts/generate_rag_faq.py <expanded_file> <final_output_file>

スクリプトが行うこと:

• jieba TF-IDF を使用してキーワードを自動生成
• プロフェッショナルな Excel フォーマットを適用
• 適切な列幅とスタイルを設定
• 最終的な重複チェックを実行
• RAG に最適化された最終ナレッジベースを作成

例:

python process-faq/scripts/generate_rag_faq.py 申花太赫兹_expanded.xlsx 申花太赫兹_RAG_优化版.xlsx

完全なワークフロー例

ユーザー: 「申花太赫兹知识库.xlsx を処理して、RAG 形式に変換してください」

あなた (Claude):

ステップ 1: Markdown に変換

python process-faq/scripts/convert_to_markdown.py 申花太赫兹知识库.xlsx

ステップ 2: 読み取りと分析

• Read ツールを使用して、生成された 申花太赫兹知识库_for_analysis.md を読み取ります
• 分析: 「元の 7 件の FAQ には、非常に長い回答 (それぞれ 500 文字以上) があることがわかりました」
• 特定: 「各回答は実際には 3〜5 の異なるトピックをカバーしています」

ステップ 3: コンテンツを拡張

• 長い回答からナレッジポイントを抽出します
• 各ポイント専用の Q&A を作成します
• 例: 「如何调理睡眠」に関する 1 つの質問から、次のように展開します:
  • 你们是怎么调理睡眠的？(调理原理)
  • 我总是入睡困难怎么办？(具体症状)
  • 先用后付是什么意思？(购买政策)
  • 为什么要用华为手环？(设备说明)
  • 手环怎么使用？(使用指南)
  • など...

ステップ 4: 拡張済み Excel を生成 pandas を使用して、31 件の焦点を絞った FAQ (元の 7 件から) を含む 申花太赫兹知识库_expanded.xlsx を作成します

ステップ 5: 形式を標準化

python process-faq/scripts/generate_rag_faq.py 申花太赫兹知识库_expanded.xlsx 申花太赫兹知识库_RAG_优化版.xlsx

ステップ 6: 結果を報告

• 「7 件の FAQ を 31 件の焦点を絞ったエントリに拡張することに成功しました」
• 「8 つのカテゴリに整理しました」
• 「すべてのエントリのキーワードを自動生成しました」
• 「最終ファイルは RAG システムで使用できる状態です」

主要な原則

1. コンテンツの拡張が鍵

あなたが提供する主な価値は次のとおりです:

• 小規模な FAQ を包括的なナレッジベースに拡張すること
• 長い回答からナレッジポイントを抽出すること
• 焦点を絞った具体的な Q&A ペアを作成すること
• 単に形式を整えたり重複を削除したりすることではありません

2. 量より質 (ただし、多い方が良い場合も多い)

• 各 FAQ は焦点を絞り、具体的であるべきです
• 長い FAQ が 5 件あるよりも、焦点を絞った FAQ が 30 件ある方が良いです
• 各回答は理想的には 50〜200 文字であるべきです
• 長い回答 (500 文字以上) は複数の FAQ に分割するべきです

3. RAG システムのように考える

• ユーザーはこの情報をどのように検索するでしょうか？
• ユーザーはどのような具体的な質問をするでしょうか？
• この回答はセマンティック検索で見つかるでしょうか？
• この質問はユーザーの意図に一致するほど具体的でしょうか？

4. 役割分担

Claude が行うこと (創造的な作業):

• コンテンツの理解
• ナレッジポイントの抽出
• 質問の分割と言い換え
• 回答の書き直し
• カテゴリの設計

スクリプトが行うこと (機械的な作業):

• キーワード抽出 (jieba TF-IDF)
• 形式の標準化
• Excel のスタイリング
• 最終的な重複チェック

品質分析と拡張チェックリスト

フェーズ A: 品質分析 (最初に必ず行うこと！)

• 矛盾がないか確認する: 異なる FAQ が矛盾する情報を提供していませんか？
• 重複を特定する: 完全な重複または意味上の重複 (同じ意味で異なる表現)
• 不整合を見つける: 類似した質問で異なる回答 (例: 異なる価格、期間)
• 不完全な情報を特定する: 回答に重要なステップや文脈が欠けていませんか？
• 不明確なコンテンツにフラグを立てる: 曖昧な質問、曖昧な用語、定義されていない専門用語
• 古い情報に注意する: 古い製品、ポリシー、価格への参照

アクション: すべての問題を記録し、解決方法を計画します

フェーズ B: コンテンツの拡張 (品質修正の後に行うこと！)

• 矛盾が解決済み: 矛盾する情報を統合しました
• 重複が統合済み: 意味上同一の質問を統合しました
• 長い回答を分割済み: 複数のトピックをカバーする 300 文字を超える回答
• 各 Q&A が焦点を絞っている: 1 つの質問 = 1 つの具体的なトピック
• すべてのナレッジポイントを抽出済み: 元の情報が失われていません
• 質問が具体的である: 「如何使用?」のような曖昧な質問を避けました
• 回答が簡潔である: 通常、回答あたり 50〜200 文字
• 回答が一貫している: 関連する FAQ が整合した情報を提供しています
• カテゴリが明確である: ドメインに基づく 5〜10 の論理的なカテゴリ
• よくある質問を追加済み: ユーザーが自然に尋ねるであろう質問を予測しました
• 適切な構造: 適切な箇所でリスト、番号付け、箇条書きを使用しました

出力形式

最終的な Excel ファイルは次のようになります。

分类	问题	回答	关键词
カテゴリ	質問	回答	キーワード

例:

分类	问题	回答	关键词
账户管理	如何重置密码?	1. 点击"忘记密码"\n2. 输入邮箱\n3. 查收重置链接	密码,重置,账户
支付问题	支持哪些支付方式?	我们支持:\n- 支付宝\n- 微信支付\n- 银行卡	支付,方式,支付宝

ベストプラクティス

1. 必ず最初に変換する: バイナリファイルを直接分析しようとしないでください
2. 徹底的に読む: 実際に Markdown ファイルを読み、ドメインを理解してください
3. 拡張よりも品質を優先する: まず問題を分析してから拡張してください
   • 壊れたコンテンツを拡張しないでください - まず修正してください!
   • さらに FAQ を作成する前に矛盾を解消してください
   • 長い回答を分割する前に重複を統合してください
4. 論理的な問題を探す:
   • FAQ 間で矛盾する情報
   • 類似した質問に対する一貫性のない回答
   • 欠落している前提条件やコンテキスト
5. ナレッジポイントを抽出する: 長い回答の中にある個別のトピックをすべて特定してください
6. 一貫性を確保する: 関連する FAQ は整合性が取れ、矛盾しない情報を提供する必要があります
7. 焦点を絞った FAQ を作成する: 各 Q&A は 1 つの特定のトピックを扱うようにしてください
8. ユーザーの視点で考える: ユーザーは何を検索するでしょうか? どのような質問をするでしょうか?
9. 中間ファイルを生成する: スクリプトを実行する前に *_expanded.xlsx を作成してください
10. キーワードはスクリプトに任せる: キーワードを手動で生成せず、jieba に任せてください

一般的な拡張シナリオ

シナリオ 1: 複数のトピックを含む長い回答

元:

Q: 你们的产品怎么样?
A: 我们的产品质量好、价格实惠、支持30天退货、全国包邮、还有24小时客服...

拡張後:

Q1: 你们的产品质量如何?
A1: 产品经过严格质检，质量可靠...

Q2: 产品价格贵吗?
A2: 价格实惠，性价比高...

Q3: 支持退货吗?
A3: 支持30天无理由退货...

Q4: 包邮吗?
A4: 全国包邮，无需额外运费...

Q5: 有客服支持吗?
A5: 提供24小时在线客服...

シナリオ 2: 曖昧な質問を具体化する必要がある

元:

Q: 如何使用?
A: [Long explanation covering installation, configuration, daily use, troubleshooting...]

拡張後:

Q1: 如何安装产品?
A1: [Installation steps]

Q2: 如何进行初始配置?
A2: [Configuration guide]

Q3: 日常使用注意事项有哪些?
A3: [Daily usage tips]

Q4: 遇到问题怎么排查?
A4: [Troubleshooting steps]

シナリオ 3: 矛盾と不整合

元 (論理的な問題あり):

Q1: 配送需要多久?
A1: 一般3-5个工作日送达

Q2: 什么时候能收到货?
A2: 通常7天内送达

Q3: 支持退货吗?
A3: 支持7天无理由退货

Q4: 可以退款吗?
A4: 不支持退款，只能换货

発見された問題:

• ❌ 矛盾: Q1 说 3-5 天，Q2 说 7 天
• ❌ 矛盾: Q3 支持退货，Q4 说不支持退款
• ⚠️ 意味的な重複: Q1 和 Q2 问的是同一件事

修正および拡張後:

Q1: 配送需要多久?
A1: 一般3-5个工作日送达（偏远地区可能需要7天）
[统一时间信息，说明例外情况]

Q2: 支持退货吗?
A2: 支持7天无理由退货退款
[解决矛盾：统一退货和退款政策]

Q3: 如何申请退货?
A3: 联系客服说明原因，获得退货地址后寄回即可
[新增：补充退货流程]

Q4: 退货运费谁承担?
A4: 质量问题我们承担，非质量问题需您承担
[新增：补充退货细节]

まとめ:

• 2 件の矛盾を解消しました
• 1 件の意味的な重複を統合しました
• 2 件の新しい関連する質問で拡張しました
• すべての情報が一貫性を持つようになりました

シナリオ 4: 明らかな質問の欠落

元: 「如何注册账户?」のみがある

以下も追加すべきです:

• 注册需要提供哪些信息?
• 可以用手机号注册吗?
• 忘记密码怎么办?
• 如何修改个人信息?
• 如何注销账户?

エラー処理

変換に失敗した場合:

• ファイル形式がサポートされているか確認してください
• ファイルが破損していないか確認してください
• まずファイルを手動で開いてみてください
• ファイルのエンコーディングを確認してください (UTF-8 である必要があります)

コンテンツが構造化されていない場合:

• Markdown には生のテキストが表示されます
• Q&A ペアを手動で特定する必要があります
• ソースドキュメントの再構築を検討してください

依存関係

必要な Python パッケージ:

• pandas (データ処理)
• openpyxl (Excel サポート)
• python-docx (Word サポート)
• PyPDF2 (PDF サポート)
• jieba (中国語テキスト処理)

インストール方法:

pip install -r process-faq/requirements.txt