1. RAGLite 连 Ollama embedding 报错问题到底出在哪RAGLite 是一个基于 Python 的检索增强生成工具包底层用 LiteLLM 统一对接各种模型提供商数据库层支持 PostgreSQL 和 SQLite检索上同时提供关键词搜索和向量搜索的混合能力。它适合谁适合想快速搭一套本地 RAG 流程、又不想自己从零写向量检索逻辑的开发者。你可以把它理解成一个「RAG 流水线组装盒」文档切块、embedding、入库、检索、重排它都帮你串好了你只需要告诉它用哪个 LLM、哪个 embedder、哪个数据库。但问题恰恰出在「告诉它用哪个 embedder」这一步。RAGLite 官方 README 给的本地示例是 llama-cpp-python 的写法embedder 字段长这样embedderllama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf1024很多人本地已经跑着 Ollama模型也 pull 好了自然想直接复用 Ollama 的 embedding 模型于是照着 LiteLLM 的命名习惯写成ollama/bge-m3。结果一跑就报连接错误要么是Connection refused要么是APIConnectionError要么是 500。核心原因有两个层面第一Ollama 原生 API 的地址是http://localhost:11434而 LiteLLM 走的是 OpenAI 兼容协议两者的 Base URL 语义不一样第二LiteLLM 在某个版本区间里对 Ollama embedding 的响应解析有 bug导致即使地址对了也会在解析阶段炸掉。我试过在同一个项目里混用本地 Ollama 和远程 OpenAI 兼容通道最容易踩的坑就是把「Ollama 服务地址」和「OpenAI 兼容 Base URL」当成同一个东西填。前者是 Ollama 自己的 REST 端口后者是带/v1路径的兼容端点。RAGLite 通过 LiteLLM 调用时LiteLLM 会根据模型前缀ollama/去决定用哪套适配器适配器内部再去拼 URL。如果你手动设了OLLAMA_API_BASE它就用你设的如果没设它默认http://localhost:11434。这一步搞清楚了后面配置就顺了。本篇要解决的就是RAGLite 通过 LiteLLM 调 Ollama embedding 时的连接报错怎么把 Base URL 配对怎么用 TaoToken 的统一 Key 和 API 通道把地址收敛成一套 OpenAI 兼容写法最后用一次 embedding 请求验证连通性和返回维度。搜索词覆盖「RAGLite Ollama embedding 连接失败」「LiteLLM Ollama embedder Base URL 配置」这类长尾问题。2. 前置准备TaoToken 通道与 Ollama 服务地址的差异在动手改配置之前先把两个地址概念分清楚这是后面所有配置的基础。Ollama 本地服务的地址默认是http://localhost:11434。它暴露的是 Ollama 自己的 API比如/api/embeddings、/api/chat。这个地址不带/v1也不是 OpenAI 兼容格式。你在浏览器里访问http://localhost:11434能看到「Ollama is running」就说明服务活着。OpenAI 兼容 Base URL 的地址通常以/v1结尾比如https://taotoken.net/api。它暴露的是/v1/embeddings、/v1/chat/completions这类标准端点。LiteLLM 在处理openai/前缀的模型时会往这个 Base URL 上拼/embeddings。而处理ollama/前缀时走的是 Ollama 适配器拼的是 Ollama 原生路径。TaoToken 在这里的角色是提供一个统一的 OpenAI 兼容通道。你可以把它当成一个「协议翻译层 统一入口」不管你后端实际接的是哪家模型对外都暴露同一套/v1接口和同一把 Key。这样你的 RAGLite 配置里就不需要为每个提供商写不同的地址和鉴权逻辑embedder 和 llm 都可以走同一个 Base URL。为什么要把 Base URL 改到 TaoToken因为本地 Ollama 的 embedding 模型受限于你机器上 pull 了哪些模型、上下文长度多少、显存够不够。而通过 TaoToken 的兼容通道你可以用同一套代码切换到更强的 embedding 模型不用改 RAGLite 的业务逻辑只改配置里的模型名和 Base URL。对于已经在用 RAGLite 做原型、又想快速对比不同 embedding 效果的场景这个收敛很省事。需要准备的东西一个 TaoToken 的 API Key在控制台创建RAGLite 装好pip install raglitePython 3.10。如果你还想保留本地 Ollama 做对比确保ollama serve在跑ollama pull好了你要用的 embedding 模型。关于 Key 的获取和通道地址可以直接看官方入口官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api模型对话体验https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc拿到 Key 之后先别急着写 RAGLite 配置用一条 curl 验证通道本身是通的这样能把「通道问题」和「RAGLite 配置问题」分开排查。curl https://taotoken.net/api/v1/embeddings \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: text-embedding-3-small, input: RAGLite embedding 连通性测试 }如果返回里能看到data[0].embedding是一个浮点数组说明通道和 Key 都没问题。这一步过了再进 RAGLite 配置。3. 可复制配置RAGLite 的 settings 与 LiteLLM 参数这一节给可直接复制的配置片段。RAGLite 的配置核心是RAGLiteConfig它接受db_url、llm、embedder等参数。embedder 的字符串格式遵循 LiteLLM 的命名规则提供商前缀/模型名。走 TaoToken 的 OpenAI 兼容通道时前缀用openai/同时通过环境变量或参数指定 Base URL 和 Key。先看环境变量部分建议放在 Python 文件最开头或者用.env加载import os os.environ[OPENAI_API_KEY] 你的 TaoToken API Key os.environ[OPENAI_API_BASE] https://taotoken.net/api注意这里用的是OPENAI_API_BASE不是OLLAMA_API_BASE。因为我们要走的是 OpenAI 兼容适配器LiteLLM 读的是OPENAI_API_BASE部分版本也认OPENAI_BASE_URL两个都设上更稳。然后是 RAGLite 的配置from raglite import RAGLiteConfig my_config RAGLiteConfig( db_urlsqlite:///raglite.db, llmopenai/gpt-4o-mini, embedderopenai/text-embedding-3-small, chunk_max_size300, embedder_sentence_window_size1, )如果你确实想保留本地 Ollama 的 embedding只是把 LLM 走 TaoToken那 embedder 仍然写ollama/bge-m3但要额外设OLLAMA_API_BASEimport os os.environ[OLLAMA_API_BASE] http://localhost:11434 os.environ[OPENAI_API_KEY] 你的 TaoToken API Key os.environ[OPENAI_API_BASE] https://taotoken.net/api from raglite import RAGLiteConfig my_config RAGLiteConfig( db_urlsqlite:///raglite.db, llmopenai/gpt-4o-mini, embedderollama/bge-m3, chunk_max_size300, embedder_sentence_window_size1, )这里有个关键点chunk_max_size默认是 1440但中文 embedding 模型上下文通常是 512。如果你用的 Ollama embedding 模型最大上下文是 512而 chunk 超过这个长度Ollama 会直接返回 500。这个报错信息很不直观容易让人以为是连接问题。所以中文场景下把chunk_max_size设成 300 左右比较安全给 token 留点余量。如果你用 TOML 或 JSON 管理配置可以这样写。先看 JSON 版本{ db_url: sqlite:///raglite.db, llm: openai/gpt-4o-mini, embedder: openai/text-embedding-3-small, chunk_max_size: 300, embedder_sentence_window_size: 1, openai_api_base: https://taotoken.net/api, openai_api_key_env: TAOTOKEN_API_KEY }TOML 版本db_url sqlite:///raglite.db llm openai/gpt-4o-mini embedder openai/text-embedding-3-small chunk_max_size 300 embedder_sentence_window_size 1 [openai] api_base https://taotoken.net/api api_key_env TAOTOKEN_API_KEY三件套对照表方便你检查有没有漏配置项本地 Ollama 写法TaoToken 兼容通道写法Base URLhttp://localhost:11434https://taotoken.net/apiKey不需要TaoToken API KeyModel IDollama/bge-m3openai/text-embedding-3-small环境变量OLLAMA_API_BASEOPENAI_API_BASEOPENAI_API_KEY注意OPENAI_API_BASE填到/api即可不要自己再拼/v1LiteLLM 会补。如果你填成https://taotoken.net/api/v1有些版本会拼成/v1/v1/embeddings导致 404。配置写好后如果你用的是 Claude Code 或类似工具做辅助开发想让它走 TaoToken 通道可以看 ClaudeCodeAnthropic 的接入说明https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode。长期做编码和 Agent 任务的话Coding Plan 更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan4. 验证请求一次 embedding 调用看连通性与返回维度配置写完必须用一次真实请求验证。不要直接跑整个 RAG 流程那样出错了你不知道是 embedding 挂了还是数据库挂了。单独调一次 embedding看返回结构和维度。先写一个最小验证脚本import os from litellm import embedding os.environ[OPENAI_API_KEY] 你的 TaoToken API Key os.environ[OPENAI_API_BASE] https://taotoken.net/api response embedding( modelopenai/text-embedding-3-small, input[RAGLite 连通性测试, 第二句话用来对比], ) print(返回类型:, type(response)) print(data 长度:, len(response.data)) print(第一条向量维度:, len(response.data[0][embedding])) print(前 5 个值:, response.data[0][embedding][:5])跑通的话你会看到类似输出返回类型: class litellm.utils.EmbeddingResponse data 长度: 2 第一条向量维度: 1536 前 5 个值: [-0.0123, 0.0456, -0.0789, 0.0234, 0.0567]维度是 1536说明text-embedding-3-small正常返回。如果你用的是text-embedding-3-large维度会是 3072。维度对上了说明通道、Key、模型名三者都正确。再验证一下 RAGLite 层面的调用。RAGLite 内部会通过 LiteLLM 调 embedding我们可以直接构造一个 config 然后触发一次 embedimport os from raglite import RAGLiteConfig from raglite._embed import embed_sentences os.environ[OPENAI_API_KEY] 你的 TaoToken API Key os.environ[OPENAI_API_BASE] https://taotoken.net/api config RAGLiteConfig( db_urlsqlite:///raglite.db, llmopenai/gpt-4o-mini, embedderopenai/text-embedding-3-small, chunk_max_size300, embedder_sentence_window_size1, ) vectors embed_sentences([测试句子一, 测试句子二], configconfig) print(向量数量:, len(vectors)) print(单条维度:, len(vectors[0]))如果这里能打印出向量数量和维度说明 RAGLite 到 LiteLLM 到 TaoToken 通道整条链路是通的。接下来你就可以正常跑insert_documents和search了。如果你同时想验证本地 Ollama 的 embedding把 embedder 换成ollama/bge-m3并设好OLLAMA_API_BASE再跑一次同样的脚本。对比两次的维度和耗时你就能直观看到本地和远程通道的差异。本地 Ollama 首次加载模型会慢之后会快远程通道稳定但受网络影响。提示验证阶段建议把input设成两条以上这样能确认批量请求也正常。有些配置单条能过、批量会触发限流或超时提前发现比上线后炸好。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来对照。你在 RAGLite Ollama TaoToken 组合里最可能碰到下面几类。401 Unauthorized / invalid api key报错长这样litellm.exceptions.AuthenticationError: OpenAIException - Error code: 401 - {error: {message: Invalid API key provided}}原因通常是OPENAI_API_KEY没设、设错或者设了但没被 LiteLLM 读到。检查顺序先echo $OPENAI_API_KEY看环境变量有没有值再看代码里是不是在 import litellm 之后才设的环境变量那样可能已经晚了要在最开头设最后确认 Key 没有多余空格或换行。如果你用的是 TaoToken 的 Key确认它是在控制台创建的、没有过期。local proxy failed / Connection refused报错长这样litellm.exceptions.APIConnectionError: OpenAIException - Connection error或者httpx.ConnectError: [Errno 111] Connection refused如果你 embedder 写的是ollama/bge-m3这个报错说明 Ollama 服务没跑或者OLLAMA_API_BASE地址不对。先curl http://localhost:11434确认服务活着。如果你 embedder 写的是openai/...这个报错说明OPENAI_API_BASE填错了或者网络到不了 TaoToken。先curl https://taotoken.net/api/v1/models -H Authorization: Bearer $TAOTOKEN_API_KEY确认通道可达。reading choices / KeyError choices报错长这样KeyError: choices或者litellm.exceptions.APIError: OpenAIException - choices这个通常出现在 LiteLLM 版本对 Ollama embedding 响应解析有 bug 的时候。Ollama 的 embedding 返回结构里没有choices字段但某些 LiteLLM 版本的适配器错误地按 chat completion 的结构去解析于是 KeyError。解决办法有两个升级 LiteLLM 到修复版本或者临时改源码。改源码的方式是找到litellm/llms/ollama/completion/handler.py把await response.json()改成response.json()。不过更推荐先升级pip install -U litellm升级后如果问题还在再考虑改源码。改之前备份文件。OAuth / Event loop is closed报错长这样RuntimeError: Event loop is closed这个出现在异步请求处理逻辑里RAGLite 和 LiteLLM 在某些版本组合下会触发。临时绕过方法是在调用 RAGLite 之前加两行import nest_asyncio nest_asyncio.apply()nest_asyncio需要先装pip install nest_asyncio。这个不是根治但能让你先把流程跑通。根治还是等 RAGLite 或 LiteLLM 官方更新。500 Internal Server ErrorOllama 侧报错长这样litellm.exceptions.APIError: OllamaException - Error code: 500如果你用的是 Ollama embedding且 chunk 长度超过了模型最大上下文Ollama 会返回 500。比如 bge-m3 的上下文是 512你 chunk 设了 1440必炸。把chunk_max_size降到 300 左右embedder_sentence_window_size设成 1再试。排查顺序建议先 curl 通道再 curl Ollama再单独调 embedding最后跑 RAGLite 完整流程。一层层缩小范围比一上来就跑全流程高效得多。6. 把 Base URL 收敛到 TaoToken 的长期用法配置跑通之后建议把 Base URL 和 Key 收敛到 TaoToken 一套通道上原因很实际你不需要在代码里维护多套地址和鉴权逻辑embedder 和 llm 都走同一个OPENAI_API_BASE切换模型只改模型名。对于 RAGLite 这种配置驱动的工具这意味着你的RAGLiteConfig可以保持稳定实验不同 embedding 模型时只动一个字符串。长期做编码和 Agent 任务的话Coding Plan 比按量更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan如果你要管理多个项目的 Key在 API Keys 页面创建和轮换https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc想先体验模型对话再决定用哪个 embedding可以在这里试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels最后给一个实用技巧把 Base URL 和 Key 放在.env里用python-dotenv加载不要硬编码在代码里。RAGLite 的配置从环境变量读这样本地开发、CI、部署环境可以用同一份代码只换.env。embedding 维度验证脚本单独存一个文件每次换模型先跑它确认维度对了再跑完整 RAG 流程。这个习惯能帮你省掉大量「以为是检索逻辑问题、其实是 embedding 没通」的排查时间。