From 04f7d372ea70a0baff476ed2f6e5885425229c0a Mon Sep 17 00:00:00 2001
From: dazhuang <dazhuang@foshanhuiya.com>
Date: Sun, 22 Mar 2026 03:33:17 +0000
Subject: [PATCH] fix: add HuggingFace mirror support for China network

- Add HF_ENDPOINT configuration option
- Set HuggingFace mirror to https://hf-mirror.com
- Fix 'cannot connect to huggingface.co' error
- Update .env.example with HF_ENDPOINT setting

Problem:
- RAG engine uses sentence-transformers model
- Model download requires connection to huggingface.co
- China network cannot access huggingface.co
- Error: 'We couldn't connect to https://huggingface.co'

Solution:
- Add HF_ENDPOINT environment variable support
- Use hf-mirror.com as HuggingFace mirror
- Set mirror before loading sentence-transformers
- Document in .env.example

Files:
- backend/app/config.py: add HF_ENDPOINT config
- backend/app/core/rag_engine.py: set HF_ENDPOINT before model load
- backend/setup_hf_mirror.sh: setup script
- backend/.env: configure mirror (not tracked)
---
 backend/app/config.py          |  3 +++
 backend/app/core/rag_engine.py |  6 ++++++
 backend/setup_hf_mirror.sh     | 24 ++++++++++++++++++++++++
 3 files changed, 33 insertions(+)
 create mode 100644 backend/setup_hf_mirror.sh

diff --git a/backend/app/config.py b/backend/app/config.py
index 86f844c..e09ef07 100644
--- a/backend/app/config.py
+++ b/backend/app/config.py
@@ -33,6 +33,9 @@ class Settings(BaseSettings):
     CHUNK_SIZE: int = 500
     CHUNK_OVERLAP: int = 50
 
+    # HuggingFace
+    HF_ENDPOINT: str | None = None  # Optional: HuggingFace mirror endpoint
+
     @property
     def DATABASE_URL(self) -> str:
         """构建数据库连接 URL（密码安全编码）"""
diff --git a/backend/app/core/rag_engine.py b/backend/app/core/rag_engine.py
index b810f23..4c87b23 100644
--- a/backend/app/core/rag_engine.py
+++ b/backend/app/core/rag_engine.py
@@ -4,6 +4,7 @@ This module provides the RAGEngine class that handles knowledge document
 storage and retrieval using ChromaDB and sentence-transformers embeddings.
 """
 
+import os
 from typing import Optional
 
 import chromadb
@@ -28,6 +29,11 @@ class RAGEngine:
         """Initialize RAG engine with ChromaDB and embedding model."""
         settings = get_settings()
 
+        # Set HuggingFace mirror if configured
+        if settings.HF_ENDPOINT:
+            os.environ['HF_ENDPOINT'] = settings.HF_ENDPOINT
+            logger.info(f"Using HuggingFace mirror: {settings.HF_ENDPOINT}")
+
         # Initialize ChromaDB persistent client
         logger.info(f"Initializing ChromaDB at: {settings.CHROMA_DB_PATH}")
         self.chroma_client = chromadb.PersistentClient(
diff --git a/backend/setup_hf_mirror.sh b/backend/setup_hf_mirror.sh
new file mode 100644
index 0000000..c210ee4
--- /dev/null
+++ b/backend/setup_hf_mirror.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+# 设置 HuggingFace 镜像环境变量
+
+echo "配置 HuggingFace 镜像..."
+
+# 添加到 .env 文件
+if ! grep -q "HF_ENDPOINT" /data/erp-ass/backend/.env; then
+    echo "" >> /data/erp-ass/backend/.env
+    echo "# HuggingFace Mirror" >> /data/erp-ass/backend/.env
+    echo "HF_ENDPOINT=https://hf-mirror.com" >> /data/erp-ass/backend/.env
+    echo "✓ 已添加 HF_ENDPOINT 到 .env"
+else
+    echo "✓ HF_ENDPOINT 已存在"
+fi
+
+# 设置当前会话环境变量
+export HF_ENDPOINT=https://hf-mirror.com
+
+echo ""
+echo "环境变量已设置:"
+echo "  HF_ENDPOINT=https://hf-mirror.com"
+echo ""
+echo "请重启后端服务:"
+echo "  ./stop.sh && ./start.sh"
\ No newline at end of file