必须通过FastAPI部署BGE模型并配置Dify使用OpenAI兼容接口，否则知识库嵌入会卡住；需严格匹配返回格式、正确设置API端点（如host.docker.internal:6008）、设为默认或手动绑定知识库，并通过测试检索验证语义匹配效果。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Dify中正确对接自建的BGE系列开源Embedding模型（如bge-m3、bge-large-zh），必须绕过OpenAI API依赖，让Dify通过标准HTTP协议调用你本地部署的FastAPI向量服务，否则知识库导入会卡在“正在嵌入”状态且无报错提示。
搭建本地BGE Embedding服务（FastAPI+SentenceTransformer）
这一步操作起来很简单，直接把代码复制进rerank.py同级目录新建一个embed_api.py文件即可运行。
安装必需依赖：pip install torch fastapi uvicorn sentence-transformers transformers huggingface-hub pyyaml
创建embed_api.py，内容如下（注意严格匹配OpenAI返回格式，否则Dify解析失败）：
import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
from fastapi import FastAPI
from sentence_transformers import SentenceTransformer
import uvicorn
app = FastAPI()
model = SentenceTransformer("BAAI/bge-m3", cache_folder="./model")
@app.post("/v1/embeddings")
def create_embedding(data: dict):
input_data = data.get("input", [])
texts = [input_data] if isinstance(input_data, str) else input_data
embeddings = model.encode(texts, normalize_embeddings=True).tolist()
return {
"object": "list",
"data": [{"object": "embedding", "embedding": emb, "index": i} for i, emb in enumerate(embeddings)],
"model": "BAAI/bge-m3",
"usage": {"prompt_tokens": len(texts), "completion_tokens": 0, "total_tokens": len(texts)}
}
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=6008)
启动服务：uvicorn embed_api.py --host 0.0.0.0 --port 6008 --reload。服务启动后访问 http://localhost:6008/docs 可看到交互式API文档，确认/v1/embeddings接口可正常POST测试。
配置Dify使用本地Embedding模型
进入Dify后台 → 设置 → 模型配置 → 文本嵌入 → 点击「+ 添加模型」
填写以下三项必填字段：
① 模型名称：bge-m3（任意命名，但需与后续知识库绑定时一致）
② 模型供应商：选择 OpenAI API 兼容
③ API端点：http://host.docker.internal:6008（若Dify运行在Docker中；若为源码启动则填http://127.0.0.1:6008）
最大Token数填512，点击「测试连接」→ 等待返回维度值（bge-m3为1024）即表示连通成功。
⚠️ 注意：host.docker.internal 是Docker容器内访问宿主机服务的关键地址，Windows/macOS Docker Desktop默认支持，Linux需手动配置DNS或改用宿主机真实IP。
绑定知识库并验证嵌入效果
方法一：全局默认绑定
在「文本嵌入」列表中，找到刚添加的bge-m3模型，点击右侧「设为默认」。此后所有新建知识库将自动使用该模型。
方法二：单知识库指定绑定
进入知识库 → 编辑 → 高级设置 → 嵌入模型 → 下拉选择bge-m3 → 保存。
上传一份含中文段落的PDF或TXT文件，观察导入日志。若出现“Embedding completed for X chunks”且无报错，则说明向量化已走通。
关键验证动作：在知识库详情页点击「测试检索」，输入“如何申请电子发票”，查看返回结果是否包含语义高度匹配的原文片段——这一步成功，代表BGE嵌入真正生效。
