mirror of
https://github.com/DayuanJiang/next-ai-draw-io.git
synced 2026-01-10 02:02:31 +08:00
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
This commit is contained in:
Dayuan Jiang
@@ -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
|
||||
|
||||
[](https://www.star-history.com/#DayuanJiang/next-ai-draw-io&type=date&legend=top-left)
|
||||
|
||||
76
docs/cn/FAQ.md
Normal file
76
docs/cn/FAQ.md
Normal file
@@ -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
|
||||
@@ -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历史
|
||||
|
||||
[](https://www.star-history.com/#DayuanJiang/next-ai-draw-io&type=date&legend=top-left)
|
||||
|
||||
76
docs/en/FAQ.md
Normal file
76
docs/en/FAQ.md
Normal file
@@ -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
|
||||
76
docs/ja/FAQ.md
Normal file
76
docs/ja/FAQ.md
Normal file
@@ -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
|
||||
@@ -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) をご覧ください。
|
||||
|
||||
## スター履歴
|
||||
|
||||
[](https://www.star-history.com/#DayuanJiang/next-ai-draw-io&type=date&legend=top-left)
|
||||
|
||||
Reference in New Issue
Block a user