1. vanna 跑 text-to-SQL 时为什么总在 Key 和 Base URL 上翻车GitHub 趋势日报里 vanna 这个项目最近又冒头了它的定位很直白用 RAG 的方式把自然语言问题转成能跑的 SQL。你给它一句“上月销售额前 5 的客户”它去检索表结构、字段注释、历史问答再让背后的 LLM 生成 SQL。适合谁适合手头有数据库、想让业务同学自己查数、又不想每次都写 SQL 的人。但真正本地跑起来卡人的往往不是 RAG 逻辑而是 LLM 的接入配置。vanna 本身不绑定某一家模型它通过 OpenAI 兼容接口去调 LLM于是你会遇到两个高频问题一是各家控制台申请的 Key 格式、额度、模型名都不一样换一个模型就要改一遍环境变量二是 Base URL 到底带不带/v1写错了直接 401 或者 404。我见过太多人在OPENAI_API_KEY和OPENAI_BASE_URL之间反复横跳最后怀疑是 vanna 的 bug其实只是路径多了一个/v1。这篇就按“验证用量”的视角来走一遍用一把统一的 Key把 vanna 环境里的 Base URL 设成https://taotoken.net/api注意不带/v1然后跑一次“上月销售额前 5 的客户”看生成的 SQL 是否正常。要强调的是这套配置解决的是 vanna 背后 LLM 的 Token 供给不是把 vanna 的检索逻辑换成别的RAG 那套还是 vanna 自己的。2. 前置准备一把 Key 和正确的 Base URL先说清楚 TaoToken 在这里的角色。它是一个统一的模型调用入口你可以在官网创建一把 Key然后在 vanna 里把 Base URL 指向它。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册和创建 Key 的入口在控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建完记得复制保存页面刷新后就看不到完整 Key 了。这里有个关键点也是最多人踩的坑Base URL 填https://taotoken.net/api不要在后面加/v1。很多 OpenAI 兼容的客户端默认会自己拼/v1/chat/completions如果你在 Base URL 里又写了一遍/v1最终请求路径就变成/api/v1/v1/chat/completions服务端自然找不到返回 404 或者路径错误。vanna 底层用的是 openai 这个 Python 包它的行为就是拿你给的 base_url 再拼/chat/completions所以 base_url 到/api为止。环境变量建议这样设先确认你的 shell 里没有旧的残留unset OPENAI_API_KEY unset OPENAI_BASE_URL export OPENAI_API_KEY你刚创建的那把Key export OPENAI_BASE_URLhttps://taotoken.net/api如果你用的是.env文件配合 python-dotenv写法一样注意不要带引号以外的空格。模型名这块vanna 默认会用一个通用模型名你可以在初始化时显式指定具体支持哪些模型名以接入文档为准文档地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先在网页上确认模型能不能正常对话可以用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一句话试试能回就说明 Key 和额度没问题。3. 可复制配置把 vanna 接到统一入口下面这段是完整的可运行示例我用 SQLite 内存库造了一张订单表方便你直接复制跑通。核心就是OpenAI客户端初始化时把api_key和base_url传对然后交给 vanna 的OpenAI_Chat和ChromaDB_VectorStore。import os import sqlite3 import pandas as pd from vanna.openai import OpenAI_Chat from vanna.chromadb import ChromaDB_VectorStore from openai import OpenAI # 1. 读取环境变量确认 Base URL 不带 /v1 api_key os.environ[OPENAI_API_KEY] base_url os.environ[OPENAI_BASE_URL] print(base_url , base_url) # 应该是 https://taotoken.net/api # 2. 自定义 vanna 类把 openai 客户端注入进去 class MyVanna(ChromaDB_VectorStore, OpenAI_Chat): def __init__(self, configNone): ChromaDB_VectorStore.__init__(self, configconfig) OpenAI_Chat.__init__(self, configconfig) client OpenAI(api_keyapi_key, base_urlbase_url) vn MyVanna(config{ client: openai, model: gpt-4o-mini, # 按接入文档支持的模型名填写 api_key: api_key, base_url: base_url, }) # 3. 造一张订单表并灌入示例数据 conn sqlite3.connect(:memory:) conn.execute( CREATE TABLE orders ( order_id INTEGER PRIMARY KEY, customer_name TEXT, amount REAL, order_date TEXT ) ) rows [ (1, 客户A, 1200.0, 2025-06-03), (2, 客户B, 800.0, 2025-06-15), (3, 客户A, 3000.0, 2025-06-21), (4, 客户C, 500.0, 2025-07-01), (5, 客户B, 2200.0, 2025-07-08), (6, 客户D, 1500.0, 2025-07-12), ] conn.executemany(INSERT INTO orders VALUES (?,?,?,?), rows) conn.commit() df pd.read_sql_query(SELECT * FROM orders, conn) vn.connect_to_sqlite(:memory:) # 演示用真实项目换成你的库 # 4. 训练元数据让 RAG 有东西可检索 vn.train(ddl CREATE TABLE orders ( order_id INTEGER PRIMARY KEY, customer_name TEXT, amount REAL, order_date TEXT ) ) vn.train(documentationorders 表记录每笔订单amount 是金额order_date 是下单日期格式 YYYY-MM-DD) # 5. 发起自然语言提问 sql vn.generate_sql(上月销售额前 5 的客户) print(生成的 SQL) print(sql)几个参数说明一下。model字段填你实际要用的模型名不同模型名对应的计费和能力不同别照抄。base_url一定要和上面环境变量一致都是https://taotoken.net/api。vn.connect_to_sqlite这里为了演示用了内存库真实场景换成你的数据库连接串vanna 支持多种数据库具体看它的文档。如果你更习惯用命令行验证也可以先用 curl 打一发确认 Key 和路径没问题再进 Pythoncurl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复 ok}] }返回里能看到choices字段就说明链路通了。这一步能帮你把“Key 错”和“vanna 配置错”分开定位。4. 验证请求跑一次“上月销售额前 5 的客户”配置好之后直接运行上面的脚本。正常情况下generate_sql会返回一段类似这样的 SQLSELECT customer_name, SUM(amount) AS total_amount FROM orders WHERE order_date 2025-06-01 AND order_date 2025-07-01 GROUP BY customer_name ORDER BY total_amount DESC LIMIT 5;注意这里的日期范围取决于你运行时的“当前月份”vanna 会把自然语言里的“上月”交给 LLM 去推断所以生成的 SQL 里日期是动态的。你要验证的不是 SQL 长得一模一样而是它结构合理有SUM、有GROUP BY、有ORDER BY DESC、有LIMIT 5字段名和你的表对得上。拿到 SQL 后可以顺手执行一下看结果result vn.run_sql(sql) print(result)如果返回了客户和金额的列表说明从自然语言到 SQL 再到执行这条链路是通的。这时候你回头看一眼调用日志或者用量页面能看到这次请求消耗的 Token 数这就是“验证用量”的意义确认 vanna 背后确实在通过你配置的入口调 LLM而不是静默失败。实测下来最容易出问题的不是 SQL 生成质量而是请求根本没发出去。所以建议在generate_sql外面包一层异常捕获把错误打全try: sql vn.generate_sql(上月销售额前 5 的客户) print(sql) except Exception as e: print(调用失败, repr(e))repr(e)能把 HTTP 状态码和响应体带出来比只打印str(e)有用得多。5. 本篇常见错排查401、404 和路径问题第一个高频错误是 401 Unauthorized。原因通常是 Key 没读到、Key 复制时带了空格、或者环境变量在另一个终端里设的。排查方法是在 Python 里打印os.environ.get(OPENAI_API_KEY)的前几位和后几位确认不是空值。如果 Key 是对的还报 401去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认这把 Key 没有被禁用或额度耗尽。第二个高频错误是 404 或者Not Found几乎都是 Base URL 多写了/v1。记住规则Base URL 到https://taotoken.net/api为止/v1由客户端自己拼。你可以用前面那条 curl 命令直接验证如果 curl 用/api/chat/completions能通而 Python 里报 404那就是 Python 侧把 base_url 写成了带/v1的版本。第三个是模型名不匹配。有些模型名在别家能用在这里不一定支持报错通常是model not found之类。解决办法是查接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的模型列表换成明确支持的名称。别凭记忆填。第四个是 vanna 的 RAG 检索为空导致 SQL 瞎编。这跟 Key 无关是你没train足够的 DDL 和文档。表现是生成的 SQL 里字段名对不上或者表名不存在。解决方法是把建表语句、字段注释、几个典型问答都vn.train进去检索质量上来了SQL 才准。第五个是代理或网络层干扰。如果你本地有全局代理可能会把请求拦到别的地方表现是超时或者证书错误。排查时先确认请求确实发到了taotoken.net可以在代码里打印实际使用的base_url或者用curl -v看连接目标。6. 长期跑编码和 Agent可以看 Coding Plan如果你只是偶尔验证一下 vanna 的 text-to-SQL上面这套配置就够了。但如果你打算把 vanna 接进日常的数据分析流程或者同时还在跑 Claude Code 这类编码 Agent长期消耗的 Token 量会上去这时候可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它的定位是给长期编码和 Agent 场景用的和单次验证的用法不一样按自己的用量节奏选就行。回到 vanna 本身这套配置的核心就一句话Base URL 用https://taotoken.net/api不带/v1Key 从控制台创建然后跑一次“上月销售额前 5 的客户”确认 SQL 正常生成。RAG 检索逻辑还是 vanna 自己的你换的只是背后 LLM 的供给入口。把这一步跑通后面接真实数据库、加更多训练数据都是顺水推舟的事。