企业官网建设流程全解析

1. 排障现场：Gemini 3.8 Live 有音频流、但没有文字回包

最近在帮一个语音智能体项目做供应商切换，场景是跑 Gemini 3.8 Live 做语音到语音对话。本地调试时遇到一个很典型的现象：WebSocket 连接建立成功，setupComplete随后返回，麦克风采集的 PCM 帧也按 100ms 一包持续上行，但下游只收到音频帧，没有serverContent.modelTurn里的转写文本，日志里也看不到usageMetadata。

前两轮排查方向全跑偏了：一会儿怀疑采样率，一会儿怀疑speechConfig的 voice name，一会儿怀疑是 Live API 的 session resumption 时间窗把上下文吃掉了。最后发现根因根本不在业务代码上，而是在供应商侧配置——请求被指到了一个只转发文本模态的兼容层，音频帧被静默丢弃。

这个坑值得写下来。音频模态的语音智能体和纯文本调用不同，音频是宿主侧持有，而不是模型侧回吐；一旦中间层对音频帧做了静默处理，模型会退化成“能连不能听”。所以本文只讲三件能落地的事：

• 语音智能体在哪里拿 Key、Base URL 怎么指；
• 音频不落盘是怎么做到的、边界在哪；
• 一次 Live 会话的 Token 究竟消耗在哪些环节，怎么归集。

先到 TaoToken 官网 拿一枚 Key，请求侧 base_url 统一指向https://taotoken.net/api。TaoToken 在这一层只签发 Key、只做请求侧鉴权与计费，不碰音频流——音频帧的体积、落盘、回收全部发生在你自己的智能体进程里，这一点对合规审计很关键。

需要先对齐一下事实：Google 在 Gemini Live API 与 AI Studio 上线了 Gemini 3.8 Live 和 Gemini 3.8 Live Extended Thinking 两款原生语音到语音对话模型，托管形式不提供开放权重。也就是说，能选的路只有托管调用，没有本地自部署兜底。这对语音智能体的架构有一个直接后果——Key 和 Base URL 就是你全部的可控面，供应商选错，排查成本会成倍上升。

2. 拿到 Key 之后：Gemini 3.8 Live 的 Base URL 与注入片段

很多人第一次接语音智能体，会下意识把 Key 写进前端 JSON，或者塞进NEXT_PUBLIC_前缀的环境变量里。这在音频场景里是双重事故：一是 Key 泄漏，二是浏览器侧直接连 WebSocket 会暴露你的供应商链路。

正确做法是智能体服务端持有 Key，客户端只连你自己的网关。下面是 Python 侧的最小注入片段，可以直接抄。注意 Base URL 用https://taotoken.net/api，不加任何 UTM 参数——UTM 只用于控制台页面归因，混进 API 基址会导致签名校验失败。

# voice_agent/config.py import os from dataclasses import dataclass @dataclass(frozen=True) class UpstreamCfg: # 控制台签发，服务端环境变量注入，禁止落到前端构建产物 api_key: str = os.environ["TAOTOKEN_API_KEY"] # 请求侧基址：只填到 /api，不要再拼子路径 base_url: str = "https://taotoken.net/api" # 语音到语音会话，走 Live 长连接 model: str = "gemini-3.8-live" # 需要更强推理时切 Extended Thinking，注意首包延迟会上升 thinking_model: str = "gemini-3.8-live-extended-thinking" # 音频不落盘：上游只接收 PCM 帧，不接收文件路径 audio_sink: str = "memory" CFG = UpstreamCfg() def assert_key_shape(key: str) -> None: # 只校验形状，不打印明文，避免日志泄漏 if not key or len(key) < 20: raise RuntimeError("TAOTOKEN_API_KEY 缺失或长度异常，请到控制台重新签发")

Node / TypeScript 侧同理，用process.env读取，不要写进任何会被打包进浏览器的文件：

// src/agent/upstream.ts export const upstream = { apiKey: process.env.TAOTOKEN_API_KEY ?? "", baseUrl: "https://taotoken.net/api", model: "gemini-3.8-live", thinkingModel: "gemini-3.8-live-extended-thinking", } as const; export function ensureKey(): void { if (!upstream.apiKey) { throw new Error("缺少 TAOTOKEN_API_KEY，请先在控制台创建 Key"); } }

Key 的签发入口在 API Keys 控制台，建议按环境分 Key（dev / staging / prod 各一枚），这样 Token 归集表天然就能按环境切分，出问题也能单独吊销一枚而不影响其他环境。

关于模型选择，这里有一条经验规则值得记住：

• 短指令、低延迟优先（比如语音点单、实时问答唤醒后的前几轮）→ 走gemini-3.8-live；
• 多步推理、需要中途思考（比如语音排障、语音填写复杂表单）→ 走gemini-3.8-live-extended-thinking，但要把首包延迟预算从 400ms 放宽到 900ms 以上，否则用户会以为掉线。

3. 音频不落盘对照：哪些环节经过 TaoToken，哪些完全在本地

这一节是本文的核心。语音智能体最容易被审计挑出来的问题不是模型答得准不准，而是“音频去哪了”。下面把一次完整语音到语音会话拆成七段，逐段标注音频控制权归属。

第 3 段和第 5 段是很多人误解的地方：“经过 TaoToken”不等于“音频被 TaoToken 存储”。TaoToken 在这条链路上只做 Key 鉴权与用量计费，音频帧是透传的，不进入任何持久化介质。真正决定音频落不落盘的，是你自己的第 1 段和第 6 段代码。

下面这段是“音频不落盘”的关键实现，重点看audio_sink = memory这个约束是怎么被强制执行的：

# voice_agent/pipeline.py import array import io from typing import Iterator from voice_agent.config import CFG class RingBuffer: """只驻留内存的采集缓冲，进程退出即释放，不 touch 磁盘。""" def __init__(self, max_seconds: int = 30, rate: int = 16000) -> None: self.cap = max_seconds * rate self.buf = array.array("h") self.rate = rate def push(self, pcm: array.array) -> None: self.buf.extend(pcm) if len(self.buf) > self.cap: del self.buf[: len(self.buf) - self.cap] def snapshot(self) -> array.array: return array.array("h", self.buf) def frame_iter(buf: RingBuffer) -> Iterator[bytes]: """按 100ms 切帧，纯内存拷贝，不写 wav。""" chunk = buf.rate // 10 pcm = buf.snapshot() for i in range(0, len(pcm) - chunk + 1, chunk): yield pcm[i : i + chunk].tobytes() def guard_no_disk_write(path_hint: str) -> io.BytesIO: """任何试图把音频写盘的分支一律抛错，防止回归。""" if CFG.audio_sink != "memory": raise RuntimeError(f"音频落盘已启用：{path_hint}，违反不落盘约束") return io.BytesIO()

反过来说，什么情况下必须落盘？只有两种：

1. 合规留证：某些行业要求留存通话录音。这时候要落盘在你自己的存储里，加密 + 生命周期策略自己做，而不是指望上游帮你存；
2. 离线评测：想用真实语音回放做回归测试。建议先把 PCM 转成只在上线前的测试环境可读的格式，生产链路永远保持memory。

第 6 段“转写文本”要单独决策。如果你开了转写，文本会经过上游，此时文本就是数据，需要按文本数据做脱敏与保留策略；如果你只需要音频到音频，建议关掉转写，既省 Token，又少一份数据暴露面。

4. 语音智能体 Token 消耗归集表：一次 Live 会话到底花在哪

语音到语音模型和纯文本模型在计费结构上最大的差别是：音频帧本身也是 Token。很多团队做预算时只算了文本回复，结果月底账单翻倍。

一次 3 分钟的 Live 对话，可以拆成下面这几类消耗。数值仅作示例，具体以你的控制台用量页为准：

把这些项按会话打到一张表里，才能真正做归集。下面是一段可运行的归集脚本骨架，从你智能体的用量回调里收集usageMetadata并落到本地 SQLite。注意：所有命令由你在本地执行，脚本不连接任何生产库。

# voice_agent/meter.py import sqlite3 import time from contextlib import closing from dataclasses import asdict, dataclass @dataclass class TurnUsage: session_id: str turn_index: int model: str audio_in_ms: int audio_out_ms: int text_in_tokens: int text_out_tokens: int thinking_tokens: int ts: float SCHEMA = """ CREATE TABLE IF NOT EXISTS live_usage ( session_id TEXT NOT NULL, turn_index INTEGER NOT NULL, model TEXT NOT NULL, audio_in_ms INTEGER NOT NULL, audio_out_ms INTEGER NOT NULL, text_in_tokens INTEGER NOT NULL, text_out_tokens INTEGER NOT NULL, thinking_tokens INTEGER NOT NULL, ts REAL NOT NULL, PRIMARY KEY (session_id, turn_index) ); """ def write_usage(u: TurnUsage, db_path: str = "./live_usage.db") -> None: with closing(sqlite3.connect(db_path)) as conn: conn.executescript(SCHEMA) cols = ",".join(asdict(u).keys()) marks = ",".join(["?"] * len(asdict(u))) conn.execute(f"INSERT OR REPLACE INTO live_usage ({cols}) VALUES ({marks})", tuple(asdict(u).values())) conn.commit() def aggregate(db_path: str = "./live_usage.db") -> list[tuple[str, int, int]]: """按会话归集：音频总时长、文本总输入、文本总输出。""" sql = """ SELECT session_id, SUM(audio_in_ms + audio_out_ms) AS audio_ms, SUM(text_in_tokens) AS tin, SUM(text_out_tokens + thinking_tokens) AS tout FROM live_usage GROUP BY session_id ORDER BY audio_ms DESC; """ with closing(sqlite3.connect(db_path)) as conn: return conn.execute(sql).fetchall() if __name__ == "__main__": demo = TurnUsage( session_id="s-2026-01-01-001", turn_index=0, model="gemini-3.8-live", audio_in_ms=2400, audio_out_ms=3100, text_in_tokens=180, text_out_tokens=95, thinking_tokens=0, ts=time.time(), ) write_usage(demo) for row in aggregate(): print(row)

这张表跑起来之后，你会发现一件反直觉的事：音频时长才是语音智能体的主成本项，文本 Token 往往是次要的。所以优化重心不在提示词上，而在“别让静音段上行”“播放完立即停收”“复用会话”这三件事上。

如果你的语音会话需要在多个供应商之间切换做对照，TaoToken 的 模型对话入口 可以先把 Key 和 Base URL 的配置流程走通，再回到你自己的智能体里替换。同一枚 Key 换环境时，记得同步更新归集表里的model字段，否则 Extended Thinking 的推理消耗会被算到标准模型头上，账单对不上。

5. 编码链路侧配置：Claude Code / Codex / CC Switch 三件套

语音智能体项目一般不会只有一个文件。真正落地时，语音链路和编码链路是两拨人在维护。这里把编码侧配置也一次讲清，避免“语音能跑但改代码的人配不对 Key”。

Claude Code：用settings.json配ANTHROPIC_*系列变量，Base URL 同样指向 TaoToken：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "claude-sonnet-4-5", "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5" }, "permissions": { "allow": ["Read", "Edit", "Bash(git *)"] } }

注意这里用的是ANTHROPIC_*前缀，因为 Claude Code 读的是 Anthropic 兼容协议。不要把这套变量名原样抄到 Codex，两者读的不是同一个配置体系。

Codex：用config.toml，字段名和 Claude Code 完全不同：

# ~/.codex/config.toml model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"

env_key指向宿主环境变量名，Key 本体仍然放在TAOTOKEN_API_KEY里，不写进 toml 明文。

CC Switch 三件套：如果你在多个供应商、多个模型之间来回切，建议固定这三样——一份供应商档案（base_url + 模型白名单）、一份环境变量映射（Key 从哪儿读）、一份回滚清单（切回旧配置的完整命令）。这三件套写进仓库的docs/里，团队换人也不会把 Key 配串。

完整的三件套示例：

# docs/switch/taotoken.env export TAOTOKEN_API_KEY="YOUR_API_KEY" export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_MODEL="gemini-3.8-live" export TAOTOKEN_THINKING_MODEL="gemini-3.8-live-extended-thinking"

# docs/switch/profile.yaml provider: taotoken base_url: https://taotoken.net/api models: realtime: gemini-3.8-live reasoning: gemini-3.8-live-extended-thinking coding: claude-sonnet-4-5 key_env: TAOTOKEN_API_KEY

# docs/switch/rollback.sh #!/usr/bin/env bash set -euo pipefail unset TAOTOKEN_API_KEY export VOICE_AGENT_PROVIDER="legacy" echo "已回滚到 legacy provider，请重启语音智能体进程"

这里还有一条硬约束要强调：编码链路上不要让 MCP / Agent 直连生产库。语音智能体的会话数据、Token 归集表都放在本地，需要查的时候由人手动执行 SQL，或者写成只读视图再开放。生产库直连一旦发生，排查成本会从“看日志”变成“看事故”。

6. 三类高频报错与排查路径

接语音智能体时，报错往往不会直接告诉你“密钥错了”。下面这三类最常撞上。

第一类：握手成功但无文本回包。上一节说过的静默丢帧。排查顺序是：先在客户端打印收到的帧类型计数（音频帧 / 文本帧 / 控制帧），再核对 base_url 是否为https://taotoken.net/api，最后确认model字段是不是拼成了不支持语音的型号。很多兼容层会接受请求但只回文本，看起来像“模型哑了”。

第二类：401 / invalid credential但 Key 肉眼没错。九成是环境变量没生效，或者 Key 里混入了首尾空白。加一行自检：

def preflight() -> None: from voice_agent.config import CFG raw = CFG.api_key assert raw == raw.strip(), "Key 首尾存在空白字符" assert not raw.startswith("Bearer "), "Key 里不要带 Bearer 前缀" assert CFG.base_url.endswith("/api"), "Base URL 应止于 /api" print("preflight ok:", CFG.model)

第三类：Token 用量对不上，账单比归集表多。通常是三类漏记：会话建立开销没算、Extended Thinking 的推理 Token 没算、静音段上行没算。建议每轮结束后立刻写一次归集表，而不是会话结束时批量写——批量写一旦进程崩溃，中间数据全丢。

排查这件事还有一个更省事的入口：先用 模型对话 把 Key 和模型跑通，确认返回正常，再把同样的 Key、同样的 Base URL 抄进语音智能体。这样能把“Key 问题”和“音频链路问题”彻底分开，排查面直接砍一半。

7. 收尾：语音智能体的可控面只有三件事

把这次排障收一下。语音到语音的智能体，看起来链路很长，但真正需要你守住的可控面其实只有三件：

• Key 归你管：服务端持有，按环境分发，不进前端产物；
• Base URL 指对：https://taotoken.net/api，止于/api；
• 音频不落盘由你保证：TaoToken 只发 Key 不碰音频，落不落盘取决于你的第 1 段采集和第 6 段转写代码。

Gemini 3.8 Live 与 3.8 Live Extended Thinking 是托管形态、无开放权重，这意味着你无法通过自部署来绕开供应商选择。既然 Key 和 Base URL 就是全部可控面，那这两样就必须配得干干净净。

下一步建议按这个顺序走：

1. 到 TaoToken 官网 注册并创建一枚 dev Key；
2. 在 API Keys 里再签一枚 staging Key，两枚分别注入不同环境；
3. 用 模型对话 验证 Key 可用；
4. 语音链路要长期跑，看 Coding Plan 的配额；
5. 编码侧配置参照 Claude Code 文档，把 settings.json 与 config.toml 一次配对。

最后补一句：Token 归集表不是财务的事，是排障的事。当你能按会话说出“这一轮上行多少毫秒音频、消耗多少文本 Token、有没有走 Extended Thinking”，语音智能体的问题就不再是玄学，而是可定位、可回归、可优化的工程量。