Upload docs/huggingface_download_and_run.md with huggingface_hub

docs/huggingface_download_and_run.md

@@ -0,0 +1,158 @@
+# 在新服务器下载并运行 ChartPipeline
+
+本文档说明如何从 Hugging Face Space 下载本项目，并在另一台服务器上运行。
+
+## 1. 下载项目
+
+如果服务器可以直接访问 Hugging Face：
+
+```bash
+pip install -U huggingface_hub
+huggingface-cli download Ray1ee01/ChartPipeline \
+  --repo-type space \
+  --local-dir ChartPipeline
+cd ChartPipeline
+```
+
+如果服务器不能直接访问外网，但可以访问 hf-mirror：
+
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+pip install -U huggingface_hub
+huggingface-cli download Ray1ee01/ChartPipeline \
+  --repo-type space \
+  --local-dir ChartPipeline
+cd ChartPipeline
+```
+
+也可以用 Git：
+
+```bash
+git clone https://huggingface.co/spaces/Ray1ee01/ChartPipeline
+cd ChartPipeline
+```
+
+## 2. 用 Docker 运行 Space Demo
+
+推荐方式。服务器需要已安装 Docker。
+
+```bash
+docker build -t chartpipeline .
+docker run --rm -p 7860:7860 chartpipeline
+```
+
+然后打开：
+
+```text
+http://服务器IP:7860
+```
+
+这个 demo 会启动 `app.py`，使用内置示例数据和 chart engine 模板生成 SVG 图表，不需要 API key。
+
+## 3. 不用 Docker 运行 Space Demo
+
+服务器需要 Python 3.10+、Node.js/npm、Chromium 或 Chrome。
+
+Ubuntu 示例：
+
+```bash
+sudo apt-get update
+sudo apt-get install -y chromium nodejs npm fonts-dejavu-core fonts-noto-cjk librsvg2-bin
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements-space.txt
+
+PUPPETEER_SKIP_DOWNLOAD=1 npm install --omit=dev --no-audit --no-fund puppeteer@24.36.1
+export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+
+python app.py
+```
+
+访问：
+
+```text
+http://服务器IP:7860
+```
+
+## 4. 命令行烟测
+
+运行 chart engine，确认浏览器渲染链路正常：
+
+```bash
+PYTHONPATH=. python modules/chart_engine/chart_engine.py \
+  --input examples/chart_engine_sample.json \
+  --name donut_plain_chart_01 \
+  --output /tmp/chartpipeline_sample.svg \
+  --html /tmp/chartpipeline_sample.html
+```
+
+成功时会看到：
+
+```text
+Chart generation succeeded.
+```
+
+输出文件在：
+
+```text
+/tmp/chartpipeline_sample.svg
+```
+
+## 5. 运行完整管道
+
+完整管道不只依赖 Space demo 文件，还需要资源目录、模型索引和 API key。
+当前 Hugging Face 仓库会包含一个 `resources/` 资源包，`config.example.py`
+默认会从这个目录读取颜色、标题、图像推荐索引和 embedding model。
+
+先复制配置模板：
+
+```bash
+cp config.example.py config.py
+```
+
+设置环境变量：
+
+```bash
+export OPENAI_API_KEY=你的API_KEY
+export OPENAI_BASE_URL=https://api.openai.com/v1
+export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+```
+
+如果你把资源放在其他位置，再额外指定：
+
+```bash
+export CHARTPIPELINE_RESOURCE_PATH=/path/to/resources
+export CHARTPIPELINE_DATA_RESOURCE_DIRS=/path/to/data_pool
+export CHARTPIPELINE_EMBED_MODEL_PATH=/path/to/resources/models/models--sentence-transformers--all-MiniLM-L6-v2/snapshots/fa97f6e7cb1a59073dff9e6b13e2715cf7475ac9
+```
+
+安装完整依赖：
+
+```bash
+pip install -r requirements.txt
+PUPPETEER_SKIP_DOWNLOAD=1 npm install
+```
+
+如果只需要验证图表模板，优先使用第 4 节的 chart engine 命令；完整 `pipeline.py` 需要确认 `config.py` 指向的资源目录真实存在。
+
+注意：全量图片素材库很大，原始图标和图片文件可能超过 25GB。仓库内资源包优先保证索引、metadata 和模型可用；如果你的任务需要 image recommender 输出真实图片 base64，需要同时准备完整的 `resources/image/images/` 和 `resources/image/attribute_icons/icons/` 素材目录。
+
+## 6. 常见问题
+
+如果下载失败，先确认是否需要 mirror：
+
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+```
+
+如果 Puppeteer 报找不到浏览器：
+
+```bash
+which chromium || which google-chrome
+export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+```
+
+如果 Chromium 在容器或服务器上启动失败，确认启动参数里包含 `--no-sandbox`。本项目的渲染脚本已经默认配置该参数。
+
+不要把真实 `config.py`、API key、`node_modules/`、`tmp/`、`output/` 上传到公开仓库。