AI 搜索部署手册

镭内容出色中心 · raycontentech.com · V3.1 · 2026-07-13

---

目录

1. 部署架构总览
2. 各租户配置清单
3. 核心文件清单
4. 日常操作：DITA 内容变更流程
   • 4.1 Admin Console 操作指南
5. 迭代新功能部署流程
6. 新租户移植流程
   • 6.3 新服务器必做的一次性 Fix 清单
7. Apache 路由配置规范
8. 故障排查手册
9. .env 配置参考
10. 版本变更日志
11. 视觉模型配置与运维 V3.1 NEW
    • 11.1 视觉模型配置参数
    • 11.2 图片大小与格式限制
    • 11.3 前端粘贴交互实现
    • 11.4 故障排查
    • 11.5 跨租户同步注意事项
12. 附录A：启动脚本模板
13. 附录B：全流水线脚本模板
14. 附录C：无前端企业的接入方案
15. 附录D：Word/Markdown 文档兼容扩展说明

---

1. 部署架构总览

┌─────────────────────────────────────────────────────┐

│         Windows 2019 云服务器                       │

│                                                     │

│  ┌──────────────┐     ┌──────────────┐              │

│  │  F: 镭内容   │     │  E: 销售易   │              │

│  │  Port 5200   │     │  Port 5201   │              │

│  │  Oxygen手册  │     │  CRM + FAQ   │              │

│  └──────┬───────┘     └──────┬───────┘              │

│         │                    │                      │

│  ┌──────▼───────────────────▼───────┐               │

│  │    Apache 443 反向代理           │               │

│  │    /chatbot/   → :5200           │               │

│  │    /chatbot-e/ → :5201           │               │

│  └──────────────────────────────────┘               │

└─────────────────────────────────────────────────────┘



外部访问：https://www.raycontentech.com/chatbot/chat

---

2. 各租户配置清单

项目	镭内容（公司）	销售易（客户A）
服务器	共用云服务器	客户自有服务器
盘符	F:	E:
工作目录	F:\aiRobot\AISearch	E:\aiRobot\AISearch
服务端口	5200	5201（或客户自定）
DB_PATH	F:/aiRobot/AISearch/metadata.db	E:/aiRobot/AISearch/metadata.db
TOP_DIR	F:/git/AI	E:/git/AI（客户DITA根目录）
OUTPUT_DIR	F:/outputDir	E:/outputDir
MODEL_LOCAL_PATH	F:/aiRobot/AISearch/model_distiluse/...	E:/aiRobot/AISearch/model_distiluse/...
PORTAL_DOC_BASE	https://www.raycontentech.com/leiPage/#/dashboard/workplace	客户自己的门户URL
Apache alias /chatbot/	http://127.0.0.1:5200/	客户服务器独立配置
Apache alias /ditasrc	F:/git/AI	E:/git/AI

---

3. 核心文件清单

3.1 必须存在的文件（每个租户目录）

[Drive]:\aiRobot\AISearch\

├── handleData_v4.py          # 主服务（AI搜索+对话+图片理解）

├── handleOriginData.py       # DITA元数据提取

├── hypergraph_builder.py     # 超图构建

├── build_hypergraph.py       # 超图构建入口

├── og_retriever.py           # OG-RAG检索

├── fact_extractor.py         # 事实抽取

├── ontology_loader.py        # 本体加载器

├── dita_ontology.json        # 领域本体定义

├── output_index.py           # 文档URL索引

├── admin_routes.py           # Admin控制台后端

├── update_index.py           # 索引重建工具

├── migrate_db.py             # DB表结构初始化

├── fix_db.py                 # DB约束修复（一次性）

├── win_utf8.py               # Windows编码修复

├── .env                      # 租户专属配置 ⚠️ 不同租户不同文件

├── .venv\                    # Python虚拟环境

├── model_distiluse\          # 向量模型（可共享或复制）

│   └── distiluse-base-multilingual-cased-v2\

├── metadata.db               # SQLite数据库（运行时生成）

├── faiss_index.bin           # 向量索引（运行时生成）

├── bm25_cache.pkl            # BM25索引（运行时生成）

├── df_meta.pkl               # 元数据缓存（运行时生成）

└── og_hypergraph.pkl         # 超图缓存（运行时生成）

3.2 运行时生成文件（不需要手动创建，不需要跨租户同步）

• metadata.db — 每次 handleOriginData.py 后自动更新
• faiss_index.bin / bm25_cache.pkl / df_meta.pkl — 每次 update_index.py 后重建
• og_hypergraph.pkl — 每次 build_hypergraph.py 后重建

---

4. 日常操作：DITA 内容变更流程

场景A：新增/修改 DITA 文件

适用：添加了新话题、更新了现有文档内容。

步骤 1 — 提交 DITA 文件到对应目录（TOP_DIR 下）



步骤 2 — 提取元数据

  cd [Drive]:\aiRobot\AISearch

  set PYTHONIOENCODING=utf-8

  call .venv\Scripts\activate.bat

  python handleOriginData.py



步骤 3 — 重建向量索引

  python update_index.py --no-ograg



步骤 4 — 重建超图

  python build_hypergraph.py



步骤 5 — 重启服务

  python -m waitress --port=5200 handleData_v4:app

场景B：仅修改了 .env 配置（含视觉模型配置）

步骤 1 — 修改 .env 文件

  notepad [Drive]:\aiRobot\AISearch\.env



步骤 2 — 重启服务（无需重建索引）

  python -m waitress --port=5200 handleData_v4:app

场景C：仅新增了 FAQ DITA 文件

步骤 1 — FAQ文件放入 TOP_DIR 对应目录



步骤 2 — 修复数据库约束（首次或DB结构变化时需要）

  python fix_db.py



步骤 3 — 提取元数据

  python handleOriginData.py

  # 确认输出中 "FAQ 条目数 > 0"



步骤 4 — 重建索引 + 超图

  python update_index.py --no-ograg

  python build_hypergraph.py



步骤 5 — 重启服务

  python -m waitress --port=5200 handleData_v4:app

4.1 Admin Console 操作指南

Admin Console 是通过 admin_routes.py + 前端 HTML 提供的管理界面。

访问方式： https://www.raycontentech.com/leiPage/ 或直接访问 Admin HTML 文件。

Admin Console 核心功能与操作场景：

功能按钮	操作场景	等同命令行
提取DITA元数据	DITA文件新增/修改后	python handleOriginData.py
重建向量索引	元数据提取完成后	python update_index.py --no-ograg
重建OG-RAG超图	索引重建完成后	python build_hypergraph.py
一键全流水线	以上三步一次完成	三条命令顺序执行
完成后重启服务	所有重建完成后	python -m waitress --port=5200 handleData_v4:app
实时日志	监控执行进度	命令行输出

---

5. 迭代新功能部署流程

5.1 仅修改 handleData_v4.py（最常见）

适用：改了 system prompt、检索权重、图片逻辑、视觉模型调用等。

步骤 1 — 备份现有文件

  copy handleData_v4.py handleData_v4.py.bak_%date:~0,4%%date:~5,2%%date:~8,2%



步骤 2 — 修改代码



步骤 3 — 语法检查

  python -m py_compile handleData_v4.py && echo OK



步骤 4 — 重启服务（无需重建索引）

  python -m waitress --port=5200 handleData_v4:app

5.2 修改了索引相关文件（hypergraph_builder / ontology_loader / dita_ontology.json）

步骤 1 — 备份并部署新文件



步骤 2 — 重建超图

  python build_hypergraph.py



步骤 3 — 重启服务

  python -m waitress --port=5200 handleData_v4:app

5.3 修改了 handleOriginData.py（数据提取逻辑变化）

步骤 1 — 部署新文件



步骤 2 — 清空并重建数据库（如DB结构有变化）

  python fix_db.py



步骤 3 — 全量重新提取

  python handleOriginData.py



步骤 4 — 全量重建索引

  python update_index.py --no-ograg

  python build_hypergraph.py



步骤 5 — 重启服务

  python -m waitress --port=5200 handleData_v4:app

5.4 跨租户同步新功能（F盘改好 → 同步到E盘/客户服务器）

# 同步代码文件（注意：不同步 .env 和数据库文件）

同步文件列表：

  handleData_v4.py          ← V3.1 含视觉理解逻辑

  handleOriginData.py

  hypergraph_builder.py

  build_hypergraph.py

  og_retriever.py

  fact_extractor.py

  ontology_loader.py

  dita_ontology.json        ← 如有租户专属版本则分别维护

  output_index.py

  admin_routes.py

  update_index.py

  fix_db.py

  win_utf8.py



不同步的文件：

  .env                      ← 每个租户独立（含视觉模型配置）

  metadata.db               ← 每个租户独立

  *.pkl / *.bin / *.npy     ← 每个租户独立（需重建）

  .venv\                    ← 每个服务器独立安装

  model_distiluse\          ← 可复制，也可独立下载

同步后在目标服务器执行：

set PYTHONIOENCODING=utf-8

call .venv\Scripts\activate.bat

python handleOriginData.py

python update_index.py --no-ograg

python build_hypergraph.py

python -m waitress --port=[端口] handleData_v4:app

---

6. 新租户移植流程

完整移植步骤（参考 migrate_to_new_server.bat）：

步骤 1 — 在新服务器上创建目录

  mkdir [Drive]:\aiRobot\AISearch



步骤 2 — 复制代码文件（见3.1清单，排除运行时生成文件）



步骤 3 — 复制模型文件

  xcopy /E F:\aiRobot\AISearch\model_distiluse [Drive]:\aiRobot\AISearch\model_distiluse



步骤 4 — 创建并配置 .env（参考第9节模板 + 第11节视觉模型配置，修改所有路径和端口）



步骤 5 — 创建 Python venv 并安装依赖

  cd [Drive]:\aiRobot\AISearch

  python -m venv .venv

  call .venv\Scripts\activate.bat

  pip install flask flask-cors faiss-cpu sentence-transformers==2.7.0 ^

    transformers==4.27.4 huggingface_hub==0.13.4 tokenizers==0.13.3 ^

    numpy==1.26.4 pandas openai python-dotenv fuzzywuzzy ^

    rank_bm25 waitress jieba requests



步骤 6 — 初始化数据库

  python migrate_db.py



步骤 7 — 提取 DITA 元数据

  python handleOriginData.py



步骤 8 — 重建索引

  python update_index.py --no-ograg

  python build_hypergraph.py



步骤 9 — 配置 Apache（见第7节）



步骤 10 — 启动服务

  python -m waitress --port=[租户端口] handleData_v4:app

6.3 新服务器必做的一次性 Fix 清单

以下修复在代码层面是一次性的，但在配置层面每个新服务器都需要执行：

Fix类型	性质	新服务器是否需要重做
build_image_urls() 重写	代码修复，已在 handleData_v4.py 里	复制文件即可，不需要重做
UPSERT_SQL 改为 INSERT OR REPLACE	代码修复，已在 handleOriginData.py	复制文件即可
fix_db.py 修复DB约束	一次性操作，每个新DB都要跑一次	✅ 每个服务器需要执行一次
migrate_db.py 初始化表	一次性操作，每次删DB重建后必须跑	✅ 每个服务器需要执行一次
LLM prompt修改	代码修复，已在 handleData_v4.py	复制文件即可
/ditasrc Apache alias	配置修复，每台服务器独立配置	✅ 每个服务器需要配置
视觉模型 .env 配置	配置项，每台服务器独立设置（见第11节）	✅ 每个服务器需要配置

新租户移植流程补充步骤：

步骤6a — 修复DB约束（每台新服务器必做）

  python fix_db.py



步骤6b — 配置 Apache /ditasrc alias（每台服务器必做）

  在 httpd-ssl.conf 中添加：

  Alias /ditasrc "[Drive]:/git/AI"



步骤6c — 配置视觉模型（V3.1 新增，每台服务器必做）

  在 .env 中添加 VISION_API_KEY 等配置（详见第11节）

  如不使用视觉功能，可跳过，系统会自动降级为纯文本模式

---

7. Apache 路由配置规范

在 C:\Apache\conf\extra\httpd-ssl.conf 的 <VirtualHost *:443> 块内添加：

镭内容（F盘，5200端口）

<Location /chatbot/>

    ProxyPass http://localhost:5200/

    ProxyPassReverse http://localhost:5200/

</Location>



Alias /ditasrc "F:/git/AI"

<Directory "F:/git/AI">

    Options FollowSymLinks

    Require all granted

    Header set Access-Control-Allow-Origin *

</Directory>

销售易（E盘，5201端口）— 如在同一台服务器

<Location /chatbot-e/>

    ProxyPass http://localhost:5201/

    ProxyPassReverse http://localhost:5201/

</Location>



Alias /ditasrc-e "E:/git/AI"

<Directory "E:/git/AI">

    Options FollowSymLinks

    Require all granted

    Header set Access-Control-Allow-Origin *

</Directory>

---

8. 故障排查手册

8.1 快速健康检查

# 检查服务是否运行

curl http://localhost:5200/health



# 预期返回（V3.1）

{

  "status": "running",

  "version": "5.6",

  "faiss": true,

  "bm25": true,

  "og_rag": true,

  "documents": 1234,

  "vision_enabled": true,          ← V3.1 新增字段

  "vision_model": "glm-4.6v"       ← V3.1 新增字段

}

8.2 常见问题及解决

症状	可能原因	解决方法
503 Service Unavailable	Apache未配置该路径 OR 服务未启动	检查httpd-ssl.conf + 确认服务在运行
"文档未包含此信息"	检索到错误文档 OR LLM prompt问题	检查DB内容 + 查看DEBUG输出
图片不显示	build_image_urls路径错误	确认/ditasrc Apache alias已配置
FAQ无法命中	未重建索引 OR doc_type未标注	python handleOriginData.py重跑
模型加载失败	MODEL_LOCAL_PATH错误	python test_model.py验证
GBK编码错误	win_utf8.py未导入	确认脚本顶部有import win_utf8
ON CONFLICT报错	DB缺少UNIQUE约束	python fix_db.py
重复循环输出	LLM temperature问题	检查frequency_penalty设置

8.3 诊断命令集

# 检查FAQ入库情况

python -c "

import sqlite3,os

from dotenv import load_dotenv

load_dotenv()

conn=sqlite3.connect(os.environ['DB_PATH'])

print('FAQ条目数:', conn.execute(\"SELECT COUNT(*) FROM metadata WHERE doc_type='faq'\").fetchone()[0])

print('总文档数:', conn.execute('SELECT COUNT(*) FROM metadata').fetchone()[0])

conn.close()

"



# 检查图片入库情况

python -c "

import sqlite3,os

from dotenv import load_dotenv

load_dotenv()

conn=sqlite3.connect(os.environ['DB_PATH'])

n=conn.execute('SELECT COUNT(*) FROM metadata WHERE images IS NOT NULL AND images != \"\"').fetchone()[0]

print('有图片文档数:', n)

conn.close()

"



# 验证模型可加载

python test_model.py



# 检查索引状态

python update_index.py --status



# V3.1 新增：验证视觉模型是否可用

curl -X POST http://localhost:5200/debug_vision \

  -H "Content-Type: application/json" \

  -d '{"image_base64":"test","question":"test"}'

---

9. .env 配置参考

# === LLM 后端 ===

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

OPENAI_API_BASE=http://localhost:5001/v1

DEFAULT_MODEL=deepseek-v3

FLASK_SECRET_KEY=your-secret-key-here



# === 视觉模型配置（V3.1 新增） ===

# 功能说明：启用后，用户在对话中粘贴的截图将被自动识别并分析

# 若留空或不配置，系统会自动降级为纯文本问答模式，不影响主流程

VISION_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

VISION_API_BASE=https://open.bigmodel.cn/api/paas/v4

VISION_MODEL=glm-4.6v

VISION_MAX_TOKENS=1000

VISION_TIMEOUT=60



# === 路径配置（每个租户必须修改） ===

DB_PATH=[Drive]:/aiRobot/AISearch/metadata.db

OUTPUT_DIR=[Drive]:/outputDir

TOP_DIR=[Drive]:/git/AI

MODEL_LOCAL_PATH=[Drive]:/aiRobot/AISearch/model_distiluse/distiluse-base-multilingual-cased-v2



# === 门户配置（每个租户必须修改） ===

PORTAL_DOC_BASE=https://www.raycontentech.com/leiPage/#/dashboard/workplace

PORTAL_PRO_ID=



# === 模型离线模式（保持不变） ===

TRANSFORMERS_OFFLINE=1

HF_HUB_OFFLINE=1

HF_DATASETS_OFFLINE=1



# === 性能调优（可选） ===

MAX_CONTEXT_CHARS=4000

MAX_STEPS_CHARS=2000

OG_TOP_K=8

OG_MAX_EDGES=5

OG_WEIGHT_BOOST=1.4



# === 编码（保持不变） ===

PYTHONIOENCODING=utf-8

---

10. 版本变更日志

版本	日期	变更内容	影响文件	需重建索引
v3.1	2026-07-13	智能视觉理解：用户在对话中粘贴截图，AI自动识别并分析图片内容。新增 VISION_API_KEY 等配置项，支持静默降级。	handleData_v4.py, .env	否
v4.1	2026-03-22	细节增强：context/steps截断优化，top_k 3→5	handleData_v4.py	否
v4.1	2026-03-23	加入win_utf8.py，解决Windows GBK编码问题	所有py文件	否
v4.1	2026-03-23	OntologyLoader集成，本体权重boost	ontology_loader.py, hypergraph_builder.py	是
v4.1	2026-03-24	FAQ DITA支持，handleOriginData.py重写	handleOriginData.py	是（全量）
v4.1	2026-03-24	FAQ检索修复：LLM prompt + 答案标签	handleData_v4.py	否
v4.1	2026-03-25	图片URL修复：build_image_urls重写	handleData_v4.py	否
v4.1	2026-03-25	图片内嵌答案（不再单独区块显示）	handleData_v4.py	否
v4.1	2026-03-25	检索准确度：rerank增强，相关性阈值，产品范围guard	handleData_v4.py	否
v2.0	2026-04-06	手册更新：补充Admin Console、一次性Fix清单、无前端接入方案、Word/MD兼容说明	OM.md	否

---

11. 视觉模型配置与运维 V3.1 NEW

V3.1 版本引入智能视觉理解能力，允许用户在对话中直接粘贴截图，AI 助手自动识别图片内容并给出专业分析。 本章详细介绍视觉模型的配置、运维和故障排查方法。

11.1 视觉模型配置参数

配置项清单

配置项	说明	必填	默认值
VISION_API_KEY	视觉模型服务商的 API 密钥	否（留空则禁用）	（空字符串）
VISION_API_BASE	视觉模型 API 接入地址	否	智谱官方地址
VISION_MODEL	使用的视觉模型名称	否	glm-4.6v
VISION_MAX_TOKENS	单次图片识别最大输出 token 数	否	1000
VISION_TIMEOUT	图片识别超时时间（秒）	否	60

配置步骤

步骤 1 — 获取视觉模型 API 密钥

  联系服务商开通视觉模型 API 权限，获取 API Key。



步骤 2 — 编辑 .env 文件

  notepad [Drive]:\aiRobot\AISearch\.env



步骤 3 — 添加视觉模型配置（示例）

  # === 视觉模型配置 ===

  VISION_API_KEY=sk-your-vision-api-key-here

  VISION_API_BASE=https://open.bigmodel.cn/api/paas/v4

  VISION_MODEL=glm-4.6v

  VISION_MAX_TOKENS=1000

  VISION_TIMEOUT=60



步骤 4 — 重启服务

  python -m waitress --port=5200 handleData_v4:app



步骤 5 — 验证配置是否生效

  curl http://localhost:5200/health

  # 确认返回中 "vision_enabled": true

11.2 图片大小与格式限制

支持的图片格式

格式	MIME 类型	支持状态	备注
PNG	image/png	✅ 推荐	截图默认格式，压缩率高
JPEG / JPG	image/jpeg	✅ 支持	适合照片类内容
GIF	image/gif	⚠️ 部分支持	仅首帧被识别
WebP	image/webp	⚠️ 视模型而定	部分视觉模型不支持
BMP / TIFF	—	❌ 不支持	建议转换为 PNG

大小与性能限制

限制项	推荐值	最大值	超限处理
单张图片大小	< 2MB	5MB	前端自动压缩或拒绝上传
图片分辨率	< 1920×1080	无硬性限制	过大时自动缩放
单次请求图片数	1 张	1 张	当前仅支持单图
识别超时时间	30-60 秒	可配置（VISION_TIMEOUT）	超时后静默降级为纯文本
Base64 编码后大小	< 3MB	约 6.7MB（5MB 原图）	前端建议压缩后转 Base64

11.3 前端粘贴交互实现

交互流程

用户操作                前端处理                      后端处理
─────────────────────────────────────────────────────────────────

1. 截取屏幕 / 复制图片   →  监听 paste 事件              →

                        →  读取剪贴板中的图片文件          →

                        →  压缩图片（可选）                →

                        →  转 Base64 编码                 →

2. Ctrl+V 粘贴到对话框  →  显示图片缩略图预览              →

                        →  构建请求 JSON：                →  接收 image_base64

                           {                                →  调用视觉模型识别

                             "query": "用户文字",            →  将识别结果拼入检索

                             "image_base64": "base64...",   →  调用 LLM 生成答案

                             "image_mime": "image/png"      →  返回图文融合回复

                           }                                →

                        →  POST /chatbot/chat             →

3. 查看 AI 回复         ←  渲染 Markdown 答案            ←

                        ←  显示参考来源                   ←

                        ←  完成                           ←

前端关键实现要点

• Paste 事件监听： 在聊天输入框监听 paste 事件，从 clipboardData 中提取图片文件
• 图片压缩： 使用 Canvas 将图片压缩至宽度 1200px、JPEG 质量 85%，控制 Base64 编码后大小在 2MB 以内
• Base64 编码： 使用 FileReader.readAsDataURL() 获取 Data URL，提取 image_mime 和 image_base64
• 缩略图预览： 粘贴后在输入区域显示图片缩略图，用户可删除后重新粘贴
• 文字可选： 支持纯图片提问（query 为空）、也支持图片+文字组合提问
• Data URL 兼容： 后端自动兼容前端传的 Data URL（data:image/png;base64,xxxx），无需前端额外处理

后端处理逻辑

1. 接收请求 → 提取 image_base64 和 image_mime

2. 检查配置 → VISION_API_KEY 是否存在

             → 不存在：跳过图片识别，按纯文本处理（静默降级）

3. 调用视觉模型 → 将图片转为结构化文字描述

4. 融合检索   → 将图片描述 + 用户 query 拼接为 retrieval_query

             → 使用 retrieval_query 进行 FAISS/BM25/DB 检索

             → 用户展示仍使用原始 query（不污染对话历史）

5. 生成答案   → 将图片描述作为额外上下文传给 LLM

             → 结合检索到的文档内容生成最终答案

6. 返回结果   → answer: HTML 格式答案

             → vision_used: true（标识本次使用了视觉理解）

             → sources: 参考来源文档

11.4 故障排查

视觉模型相关问题

症状	可能原因	解决方法
粘贴图片后无视觉分析	VISION_API_KEY 未配置或无效	检查 .env 中 VISION_API_KEY 是否配置正确，重启服务
图片识别响应极慢 (>30s)	图片过大 / 视觉模型服务商响应慢	前端压缩图片；检查 VISION_TIMEOUT 设置；更换服务商
识别结果不准确	图片模糊 / 内容过于复杂	建议用户截取更清晰的图片；缩小截图范围聚焦关键区域
粘贴图片后报错 503	视觉模型服务不可用	检查 VISION_API_BASE 是否可达；确认服务商状态
Base64 解码失败	前端编码格式不正确	确认前端使用标准 Base64 编码；后端已兼容 Data URL 格式
health 接口 vision_enabled 为 false	VISION_API_KEY 为空或初始化失败	检查 .env 配置；查看启动日志中的 Vision client 初始化信息

诊断命令

# 检查视觉模型配置是否生效
curl http://localhost:5200/health | python -m json.tool

# 预期输出关键字段：
#   "vision_enabled": true,
#   "vision_model": "glm-4.6v",



# 测试视觉模型连通性（使用测试图片）
curl -X POST http://localhost:5200/debug_vision \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
    "question": "这是什么？"
  }'

# 预期返回：description 不为空，success 为 true



# 检查日志中的视觉模型初始化信息
grep "VISION\|Vision\|vision" handleData_v4.py.log

# 预期看到：
#   OK Vision client ready: glm-4.6v @ https://...
# 或：
#   Vision: DISABLED (no VISION_API_KEY)

11.5 跨租户同步注意事项

同步清单（V3.1 新增项）

项目	是否需同步	说明
handleData_v4.py（含视觉逻辑）	✅ 是	主服务文件，含图片识别和融合检索逻辑
VISION_API_KEY	❌ 否	每个租户独立配置，绝对不可共享
VISION_API_BASE / VISION_MODEL	⚠️ 视情况	可共用同一服务商，但建议各租户独立配置
前端粘贴交互代码	✅ 是	leiPage 前端需更新以支持图片粘贴

---

附录A：启动脚本模板（start.bat）

每个租户目录保存一份，端口和路径按需修改：

@echo off

cd /d F:\aiRobot\AISearch

call .venv\Scripts\activate.bat

set PYTHONIOENCODING=utf-8

set PYTHONUTF8=1

echo 启动 AI Search 服务...

python -m waitress --port=5200 handleData_v4:app

pause

附录B：全流水线脚本模板（rebuild_all.bat）

DITA 内容大更新后使用：

@echo off

cd /d F:\aiRobot\AISearch

call .venv\Scripts\activate.bat

set PYTHONIOENCODING=utf-8

echo [1/4] 提取 DITA 元数据...

python handleOriginData.py

echo [2/4] 重建向量索引...

python update_index.py --no-ograg

echo [3/4] 重建超图...

python build_hypergraph.py

echo [4/4] 重启服务...

python -m waitress --port=5200 handleData_v4:app

pause

附录C：无前端企业的接入方案

对于没有自己前端的企业，有两种接入方式：

方式A：提供 leiPage 前端（最快）

直接把 F:/leineirong/page/dist 部署到客户服务器，修改前端配置里的 API 地址指向客户的 /chatbot/ 端点即可，不需要重新开发。

V3.1 注意：leiPage 前端需更新到支持图片粘贴的版本。如果客户前端版本较旧，需要同步更新前端代码。

部署步骤：

1. 复制 F:/leineirong/page/dist 到客户服务器（确保为 V3.1 支持图片粘贴的版本）
2. 修改前端配置文件中的 API 地址为客户服务器的 /chatbot/ 端点
3. 配置 Web 服务器（Nginx/Apache）托管静态文件
4. 确认 .env 中 VISION_API_KEY 已配置

方式B：嵌入式 Widget（更灵活）

提供一段 JavaScript 嵌入代码，客户把它放进自己已有网站，AI 助理悬浮窗就会出现，后端仍然调用 /chatbot/chat 接口。

V3.1 注意：Widget 需要更新以支持图片粘贴功能。旧版 Widget 仍可使用，但不支持图片粘贴。

两种方式对比：

	方式A：leiPage	方式B：Widget
客户有无前端	无需前端	有无均可
部署难度	低（复制dist目录）	极低（一段JS）
图片粘贴支持	✅ V3.1 原生支持	✅ V3.1 需更新 Widget
品牌定制	需改配置	只改颜色/LOGO
数据隔离	独立服务器	共用或独立均可

附录D：Word/Markdown 文档兼容扩展说明

当前状态：不具备，需要扩展 handleOriginData.py。

格式	当前支持	扩展难度
.dita / .xml	✅ 完整支持	—
.md (Markdown)	❌ 未支持	★☆☆☆☆ 极低，Python 原生解析
.docx (Word)	❌ 未支持	★★☆☆☆ 低，用 python-docx
.pdf	❌ 未支持	★★★☆☆ 中，用 pdfplumber
.html	⚠️ 部分（仅DITA输出）	★☆☆☆☆ 极低

扩展说明：

Markdown 和 Word 扩展只需在 handleOriginData.py 里增加两个解析分支，核心检索和 LLM 层完全不需要修改。视觉理解功能与文档格式无关，不受此扩展影响。

所需依赖：

# Markdown 支持

pip install markdown



# Word 支持

pip install python-docx



# PDF 支持

pip install pdfplumber

---

本文档由镭内容出色中心维护。每次部署新功能后，请在第10节更新变更日志。V3.1 视觉理解功能由 AI 搜索团队开发维护。