From d71fe70cbeb10462fbd373552da22561161f9ef1 Mon Sep 17 00:00:00 2001 From: Dayuan Jiang <34411969+DayuanJiang@users.noreply.github.com> Date: Fri, 9 Jan 2026 13:30:07 +0900 Subject: [PATCH] docs: add FAQ documentation for common issues (#544) - Add FAQ.md in English, Chinese, and Japanese - Link FAQ from each language README - Cover: PDF export, offline deployment, self-hosted models, image upload --- README.md | 5 +++ docs/cn/FAQ.md | 76 ++++++++++++++++++++++++++++++++++++++++++++ docs/cn/README_CN.md | 5 +++ docs/en/FAQ.md | 76 ++++++++++++++++++++++++++++++++++++++++++++ docs/ja/FAQ.md | 76 ++++++++++++++++++++++++++++++++++++++++++++ docs/ja/README_JA.md | 5 +++ 6 files changed, 243 insertions(+) create mode 100644 docs/cn/FAQ.md create mode 100644 docs/en/FAQ.md create mode 100644 docs/ja/FAQ.md diff --git a/README.md b/README.md index 5b9e5b3..7db249a 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ https://github.com/user-attachments/assets/9d60a3e8-4a1c-4b5e-acbb-26af2d3eabd1 - [Multi-Provider Support](#multi-provider-support) - [How It Works](#how-it-works) - [Support \& Contact](#support--contact) + - [FAQ](#faq) - [Star History](#star-history) ## Examples @@ -246,6 +247,10 @@ For support or inquiries, please open an issue on the GitHub repository or conta - Email: me[at]jiang.jp +## FAQ + +See [FAQ](./docs/en/FAQ.md) for common issues and solutions. + ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=DayuanJiang/next-ai-draw-io&type=date&legend=top-left)](https://www.star-history.com/#DayuanJiang/next-ai-draw-io&type=date&legend=top-left) diff --git a/docs/cn/FAQ.md b/docs/cn/FAQ.md new file mode 100644 index 0000000..b8180c8 --- /dev/null +++ b/docs/cn/FAQ.md @@ -0,0 +1,76 @@ +# 常见问题解答 (FAQ) + +--- + +## 1. 无法导出 PDF + +**问题**: Web 版点击导出 PDF 后跳转到 `convert.diagrams.net/node/export` 然后无响应 + +**原因**: 嵌入式 Draw.io 不支持直接 PDF 导出，依赖外部转换服务，在 iframe 中无法正常工作 + +**解决方案**: 先导出为图片（PNG），再打印转成 PDF + +**相关 Issue**: #539, #125 + +--- + +## 2. 无法访问 embed.diagrams.net（离线/内网部署） + +**问题**: 内网环境提示"找不到 embed.diagrams.net 的服务器 IP 地址" + +**关键点**: `NEXT_PUBLIC_*` 环境变量是**构建时**变量，会被打包到 JS 代码中，**运行时设置无效**！ + +**解决方案**: 必须在构建时通过 `args` 传入： + +```yaml +# docker-compose.yml +services: + drawio: + image: jgraph/drawio:latest + ports: ["8080:8080"] + next-ai-draw-io: + build: + context: . + args: + - NEXT_PUBLIC_DRAWIO_BASE_URL=http://你的服务器IP:8080/ + ports: ["3000:3000"] + env_file: .env +``` + +**内网用户**: 在外网修改 Dockerfile 并构建镜像，再传到内网使用 + +**相关 Issue**: #295, #317 + +--- + +## 3. 自建模型只思考不画图 + +**问题**: 本地部署的模型（如 Qwen、LiteLLM）只输出思考过程，不生成图表 + +**可能原因**: +1. **模型太小** - 小模型难以正确遵循 tool calling 指令，建议使用 32B+ 参数的模型 +2. **未开启 tool calling** - 模型服务需要配置 tool use 功能 + +**解决方案**: 开启 tool calling，例如 vLLM： +```bash +python -m vllm.entrypoints.openai.api_server \ + --model Qwen/Qwen3-32B \ + --enable-auto-tool-choice \ + --tool-call-parser hermes +``` + +**相关 Issue**: #269, #75 + +--- + +## 4. 上传图片后提示"未提供图片" + +**可能原因**: +1. 模型不支持视觉功能（如 Kimi K2、DeepSeek、Qwen 文本模型） + +**解决方案**: +- 使用支持视觉的模型：GPT-4o、Claude 3.5 Sonnet、Gemini Pro Vision +- 模型名带 `vision` 或 `vl` 的支持图片 +- 更新到最新版本（v0.4.9+） + +**相关 Issue**: #324, #421, #469 diff --git a/docs/cn/README_CN.md b/docs/cn/README_CN.md index 67ab4c0..a2c94ec 100644 --- a/docs/cn/README_CN.md +++ b/docs/cn/README_CN.md @@ -42,6 +42,7 @@ https://github.com/user-attachments/assets/b2eef5f3-b335-4e71-a755-dc2e80931979 - [多提供商支持](#多提供商支持) - [工作原理](#工作原理) - [支持与联系](#支持与联系) + - [常见问题](#常见问题) - [Star历史](#star历史) ## 示例 @@ -238,6 +239,10 @@ npm run dev - 邮箱：me[at]jiang.jp +## 常见问题 + +请参阅 [FAQ](./FAQ.md) 了解常见问题和解决方案。 + ## Star历史 [![Star History Chart](https://api.star-history.com/svg?repos=DayuanJiang/next-ai-draw-io&type=date&legend=top-left)](https://www.star-history.com/#DayuanJiang/next-ai-draw-io&type=date&legend=top-left) diff --git a/docs/en/FAQ.md b/docs/en/FAQ.md new file mode 100644 index 0000000..4788480 --- /dev/null +++ b/docs/en/FAQ.md @@ -0,0 +1,76 @@ +# Frequently Asked Questions (FAQ) + +--- + +## 1. Cannot Export PDF + +**Problem**: Web version redirects to `convert.diagrams.net/node/export` when exporting PDF, then nothing happens + +**Cause**: Embedded Draw.io doesn't support direct PDF export, it relies on external conversion service which doesn't work in iframe + +**Solution**: Export as image (PNG) first, then print to PDF + +**Related Issues**: #539, #125 + +--- + +## 2. Cannot Access embed.diagrams.net (Offline/Intranet Deployment) + +**Problem**: Intranet environment shows "Cannot find server IP address for embed.diagrams.net" + +**Key Point**: `NEXT_PUBLIC_*` environment variables are **build-time** variables, they get bundled into JS code. **Runtime settings don't work!** + +**Solution**: Must pass via `args` at build time: + +```yaml +# docker-compose.yml +services: + drawio: + image: jgraph/drawio:latest + ports: ["8080:8080"] + next-ai-draw-io: + build: + context: . + args: + - NEXT_PUBLIC_DRAWIO_BASE_URL=http://your-server-ip:8080/ + ports: ["3000:3000"] + env_file: .env +``` + +**Intranet Users**: Modify Dockerfile and build image on external network, then transfer to intranet + +**Related Issues**: #295, #317 + +--- + +## 3. Self-hosted Model Only Thinks But Doesn't Draw + +**Problem**: Locally deployed models (e.g., Qwen, LiteLLM) only output thinking process, don't generate diagrams + +**Possible Causes**: +1. **Model too small** - Small models struggle to follow tool calling instructions correctly, recommend 32B+ parameter models +2. **Tool calling not enabled** - Model service needs tool use configuration + +**Solution**: Enable tool calling, e.g., vLLM: +```bash +python -m vllm.entrypoints.openai.api_server \ + --model Qwen/Qwen3-32B \ + --enable-auto-tool-choice \ + --tool-call-parser hermes +``` + +**Related Issues**: #269, #75 + +--- + +## 4. "No Image Provided" After Uploading Image + +**Possible Causes**: +1. Model doesn't support vision (e.g., Kimi K2, DeepSeek, Qwen text models) + +**Solution**: +- Use vision-capable models: GPT-4o, Claude 3.5 Sonnet, Gemini Pro Vision +- Models with `vision` or `vl` in name support images +- Update to latest version (v0.4.9+) + +**Related Issues**: #324, #421, #469 diff --git a/docs/ja/FAQ.md b/docs/ja/FAQ.md new file mode 100644 index 0000000..ced5c47 --- /dev/null +++ b/docs/ja/FAQ.md @@ -0,0 +1,76 @@ +# よくある質問 (FAQ) + +--- + +## 1. PDFをエクスポートできない + +**問題**: Web版でPDFエクスポートをクリックすると `convert.diagrams.net/node/export` にリダイレクトされ、その後何も起こらない + +**原因**: 埋め込みDraw.ioは直接PDFエクスポートをサポートしておらず、外部変換サービスに依存しているが、iframe内では正常に動作しない + +**解決策**: まず画像（PNG）としてエクスポートし、その後PDFに印刷する + +**関連Issue**: #539, #125 + +--- + +## 2. embed.diagrams.netにアクセスできない（オフライン/イントラネットデプロイ） + +**問題**: イントラネット環境で「embed.diagrams.netのサーバーIPアドレスが見つかりません」と表示される + +**重要**: `NEXT_PUBLIC_*` 環境変数は**ビルド時**変数であり、JSコードにバンドルされます。**実行時の設定は無効です！** + +**解決策**: ビルド時に `args` で渡す必要があります： + +```yaml +# docker-compose.yml +services: + drawio: + image: jgraph/drawio:latest + ports: ["8080:8080"] + next-ai-draw-io: + build: + context: . + args: + - NEXT_PUBLIC_DRAWIO_BASE_URL=http://あなたのサーバーIP:8080/ + ports: ["3000:3000"] + env_file: .env +``` + +**イントラネットユーザー**: 外部ネットワークでDockerfileを修正してイメージをビルドし、イントラネットに転送する + +**関連Issue**: #295, #317 + +--- + +## 3. 自前モデルが思考するだけで描画しない + +**問題**: ローカルデプロイのモデル（Qwen、LiteLLMなど）が思考過程のみを出力し、図表を生成しない + +**考えられる原因**: +1. **モデルが小さすぎる** - 小さいモデルはtool calling指示に正しく従うことが難しい、32B+パラメータのモデルを推奨 +2. **tool callingが有効になっていない** - モデルサービスでtool use機能を設定する必要がある + +**解決策**: tool callingを有効にする、例えばvLLM： +```bash +python -m vllm.entrypoints.openai.api_server \ + --model Qwen/Qwen3-32B \ + --enable-auto-tool-choice \ + --tool-call-parser hermes +``` + +**関連Issue**: #269, #75 + +--- + +## 4. 画像アップロード後「画像が提供されていません」と表示される + +**考えられる原因**: +1. モデルがビジョン機能をサポートしていない（Kimi K2、DeepSeek、Qwenテキストモデルなど） + +**解決策**: +- ビジョン対応モデルを使用：GPT-4o、Claude 3.5 Sonnet、Gemini Pro Vision +- モデル名に `vision` または `vl` が含まれているものは画像をサポート +- 最新バージョン（v0.4.9+）にアップデート + +**関連Issue**: #324, #421, #469 diff --git a/docs/ja/README_JA.md b/docs/ja/README_JA.md index db2267a..3018440 100644 --- a/docs/ja/README_JA.md +++ b/docs/ja/README_JA.md @@ -42,6 +42,7 @@ https://github.com/user-attachments/assets/b2eef5f3-b335-4e71-a755-dc2e80931979 - [マルチプロバイダーサポート](#マルチプロバイダーサポート) - [仕組み](#仕組み) - [サポート＆お問い合わせ](#サポートお問い合わせ) + - [よくある質問](#よくある質問) - [スター履歴](#スター履歴) ## 例 @@ -239,6 +240,10 @@ AWS BedrockとOpenRouter以外のすべてのプロバイダーはカスタム - メール：me[at]jiang.jp +## よくある質問 + +一般的な問題と解決策については [FAQ](./FAQ.md) をご覧ください。 + ## スター履歴 [![Star History Chart](https://api.star-history.com/svg?repos=DayuanJiang/next-ai-draw-io&type=date&legend=top-left)](https://www.star-history.com/#DayuanJiang/next-ai-draw-io&type=date&legend=top-left)