1. 从零搭 RAG 智能体为什么第一步不是写代码而是管好 Key如果你刚开始接触大模型想用 Python 做一个能查自己文档、能回答问题的 RAG 智能体大概率会卡在同一个地方Key 太多、太乱、太容易泄露。检索用一个模型、生成用另一个模型、智能体规划可能还要第三个模型每个平台一套 Key、一套计费、一套限流配置文件里塞满明文密钥换台机器就得重新配一遍。RAG 智能体说白了就是给大模型外挂一个资料库你问问题它先去资料库里检索相关片段再把片段和问题一起交给模型生成答案。听起来简单但真正跑起来会涉及嵌入模型、对话模型、可能还有重排模型每个模型背后都是一个 API 端点和一个 Key。小白最容易犯的错就是把 Key 硬编码在main.py里然后不小心推到 GitHub。这篇要解决的就是这个前置问题用 TaoToken 的统一 Key 把多模型调用收敛成一个入口再给你一份可复制的settings.json和config.toml配置骨架最后跑通一条完整的 RAG 检索加智能体调用链路。你不需要先成为 AI 专家只要会装 Python、会改配置文件就能跟着做完。适合谁看刚学 Python 不久、想做一个能写进简历的 AI 小项目、但被各种 API Key 和模型名搞晕的程序员。全程用命令行和配置文件不涉及复杂框架源码。2. TaoToken 统一 Key 前置准备一个入口管住所有模型TaoToken 的核心价值是把不同模型的调用统一到一个 API 地址和一把 Key 上。你不需要为每个模型单独注册、单独充值、单独记 Key只要在控制台生成一个 Key然后在代码里把 base_url 指向 TaoToken 的 API 地址模型名按文档填对应标识即可。先做三件事。第一打开官网了解整体能力地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去后先看文档和模型列表确认你要用的嵌入模型和对话模型都在支持范围内。第二进入控制台创建 API Key控制台入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 生成的 Key 只显示一次复制后立刻存进环境变量别写在代码里。第三如果你打算长期做编码类智能体可以顺手看看 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用场景。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 OpenAI 兼容客户端的 base_url 使用。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面会写清楚每个模型对应的 model 名称配置时以文档为准不要凭记忆猜。注意Key 只存在环境变量或本地未提交的配置文件里。如果你用 Git先把.env和config.local.toml加进.gitignore这一步比写代码重要。环境准备清单Python 3.10 以上、VS Code、Git以及一个用来放文档的文件夹。RAG 的“资料库”初期就用几个 Markdown 文件即可不需要一上来就上向量数据库集群。3. 可复制配置骨架settings.json 与 config.toml配置分两层一层是应用级设置用settings.json一层是模型与检索参数用config.toml。这样拆的好处是换模型只改 toml换运行环境只改 json互不干扰。先建项目目录mkdir rag-agent-demo cd rag-agent-demo python -m venv .venv source .venv/bin/activate pip install openai chromadb python-dotenv tomliWindows 激活命令换成.venv\Scripts\activate。安装的四个包分别负责调用模型、本地向量库、读取环境变量、解析 toml。settings.json骨架如下放在项目根目录{ app_name: rag-agent-demo, docs_dir: ./docs, vector_store_dir: ./.chroma, collection_name: my_notes, top_k: 4, chunk_size: 500, chunk_overlap: 80, log_level: INFO }docs_dir指向你放 Markdown 笔记的目录top_k是每次检索返回的片段数chunk_size和chunk_overlap控制文本切分粒度。小白常把 chunk 设得太大导致检索命中不精准500 字左右配 80 字重叠是比较稳的起点。config.toml骨架如下[api] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models] embedding 你的嵌入模型名 chat 你的对话模型名 [retrieval] top_k 4 score_threshold 0.3 [agent] max_steps 5 system_prompt 你是一个基于检索结果回答问题的助手只依据提供的上下文作答不知道就说不知道。api_key_env写的是环境变量名不是 Key 本身。模型名去接入文档里对照填写。score_threshold用来过滤低相关片段太低会引入噪声太高会检索不到内容0.3 是常见起点。环境变量这样设export TAOTOKEN_API_KEY你复制的KeyWindows PowerShell 用$env:TAOTOKEN_API_KEY你的Key。设完可以用echo $TAOTOKEN_API_KEY确认非空。4. 跑通检索与智能体调用验证请求与成功结果配置就绪后先验证模型连通再验证检索最后串成智能体。分三步走每步都有明确的成功标志。第一步写一个最小连通测试check_api.pyimport os from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( model你的对话模型名, messages[{role: user, content: 只回复两个字通了}], ) print(resp.choices[0].message.content)运行python check_api.py终端打印“通了”就说明 Key 和 base_url 都正确。如果报 401检查环境变量是否生效报 404检查模型名是否和文档一致。第二步建索引并检索。把几篇 Markdown 放进docs/然后写build_index.pyimport json, os, tomli from openai import OpenAI import chromadb cfg tomli.load(open(config.toml, rb)) settings json.load(open(settings.json)) client OpenAI(base_urlcfg[api][base_url], api_keyos.environ[cfg[api][api_key_env]]) chroma chromadb.PersistentClient(pathsettings[vector_store_dir]) col chroma.get_or_create_collection(settings[collection_name]) def chunk(text, size, overlap): out, i [], 0 while i len(text): out.append(text[i:isize]) i size - overlap return out docs, ids, metas [], [], [] for fn in os.listdir(settings[docs_dir]): if not fn.endswith(.md): continue text open(os.path.join(settings[docs_dir], fn), encodingutf-8).read() for j, c in enumerate(chunk(text, settings[chunk_size], settings[chunk_overlap])): docs.append(c); ids.append(f{fn}-{j}); metas.append({source: fn}) emb client.embeddings.create(modelcfg[models][embedding], inputdocs) col.add(idsids, documentsdocs, metadatasmetas, embeddings[e.embedding for e in emb.data]) print(f已写入 {len(docs)} 个片段)运行后看到“已写入 N 个片段”说明嵌入模型调用和向量写入都成功。这一步最容易踩的坑是文档编码统一用 UTF-8 保存。第三步检索加生成写ask.pyimport json, os, sys, tomli from openai import OpenAI import chromadb cfg tomli.load(open(config.toml, rb)) settings json.load(open(settings.json)) client OpenAI(base_urlcfg[api][base_url], api_keyos.environ[cfg[api][api_key_env]]) col chromadb.PersistentClient(pathsettings[vector_store_dir]) \ .get_collection(settings[collection_name]) q sys.argv[1] qe client.embeddings.create(modelcfg[models][embedding], input[q]) hits col.query(query_embeddings[qe.data[0].embedding], n_resultscfg[retrieval][top_k]) context \n---\n.join(hits[documents][0]) resp client.chat.completions.create( modelcfg[models][chat], messages[ {role: system, content: cfg[agent][system_prompt]}, {role: user, content: f上下文\n{context}\n\n问题{q}}, ], ) print(resp.choices[0].message.content)运行python ask.py 你的问题如果回答内容明显引用了你文档里的信息而不是泛泛而谈说明整条 RAG 链路通了。成功标志有两个检索返回的片段和问题相关生成答案里出现了文档中的专有名词。5. 本篇常见错排查Key、模型名、检索为空接入阶段最高频的报错是 401 和 404。401 基本都是 Key 没读到先确认echo $TAOTOKEN_API_KEY有输出再确认代码里读的是同一个环境变量名。404 通常是模型名写错去接入文档复制准确名称注意大小写和连字符。检索为空是第二类高频问题。表现是hits[documents][0]为空列表或者答案说“没有相关信息”。原因一般有三个文档没写进向量库、查询嵌入和文档嵌入用了不同模型、top_k设成了 0。排查顺序是先打印集合数量col.count()如果是 0 就重新跑build_index.py数量正常但检索为空检查嵌入模型是否前后一致。第三类是配置解析错误。tomli对格式敏感字符串必须加引号布尔值不能写成True以外的形式。如果报TOMLDecodeError把config.toml贴进在线校验器逐行看。另外settings.json里不能写注释JSON 不支持注释写了会解析失败。第四类是中文乱码。文档读取时显式指定encodingutf-8终端如果显示乱码Windows 下执行chcp 65001切到 UTF-8 代码页。提示每次改完配置先跑check_api.py确认模型通再跑ask.py。把问题隔离在最小步骤里比一次性跑全流程好排查。如果你在接入文档里找不到对应模型的名称或者 Key 权限有问题直接去 API Keys 页面重新生成一把入口是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成后更新环境变量再测。想先不写代码、直接对话验证模型效果可以用模型对话页面入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。6. 把统一 Key 接进你的长期 AI 工作流跑通这个 demo 之后你手里其实已经有了一套可复用的骨架settings.json管应用参数config.toml管模型和检索环境变量管密钥三者分离。以后换模型只改 toml 里一行换项目只改 json 里路径Key 始终不落盘到代码仓库。下一步可以做的扩展把ask.py包成一个函数加上多轮对话历史把检索结果加上来源文件名让答案可溯源把max_steps用起来做一个能自己决定“要不要再检索一次”的简单智能体循环。这些都不需要换 Key统一入口已经帮你把模型调用这层抽象掉了。长期做编码类智能体的话Coding Plan 会比按次调用更省心入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果你更习惯在 Claude Code 这类工具里工作可以看 Anthropic 接入说明入口是 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 把统一 Key 配进去工具链和自建项目共用一套凭证。最后留一个实用习惯每次新建项目先把.env、config.local.toml、.chroma/写进.gitignore再开始写第一行业务代码。这个动作花十秒能省掉后面删仓库重来的麻烦。