1. 从对话到服务响应SKILL 参数化模板为什么总在意图识别上翻车做讯飞AI开发者大赛「智能服务与陪伴」赛道的 SKILL最容易踩的坑不是模板写得不好而是自然语言理解这一层没接稳。用户说“明天下午三点提醒我买菜”你的 Python 脚本如果只认15:00这种格式意图识别直接失败用户说“冰箱里有鸡蛋番茄能做啥”你的菜谱模板如果只会按固定份量输出参数化就变成了硬编码。我这次要交付的是一条完整链路对话输入 → 自然语言理解 → 意图路由 → 参数化模板渲染 → 服务响应。核心工具是 Python TaoToken 统一 Key。TaoToken 在这里的角色是提供一个兼容 OpenAI 接口规范的调用入口让你不用为每个模型单独维护一套 Key 和 SDK一个 Key 打通意图识别和内容生成两个环节。适合谁看正在做讯飞 AI 开发者大赛 SKILL 类赛题智慧生活助理、教育智能辅助、智能办公协同助理三个方向都适用的开发者已经有一套 Python 参数化模板、但意图识别层还在用关键词匹配硬扛的同学以及想把多个模型调用收敛到一个配置里的工程实践者。下面按“先跑通再优化”的顺序来先给 config.toml 和 settings.json 骨架再写意图识别与模板渲染的 Python 代码最后用真实请求验证整条链路。2. TaoToken 前置统一 Key 与项目结构2.1 为什么 SKILL 项目需要统一 Key一个 SKILL 通常至少有两类模型调用一类做意图识别把用户口语映射到场景路由一类做内容生成填充参数化模板。如果意图识别用一个厂商、内容生成用另一个厂商你的代码里就会出现两套鉴权逻辑、两套超时重试、两套错误码解析。SKILL 本身是给评审看工程质量的这种分裂结构很扣分。TaoToken 的做法是提供一个统一的 API 入口模型名通过参数切换。你只需要在配置里写一次base_url和api_key意图识别和内容生成走同一个客户端只是model字段不同。2.2 获取 Key 与项目目录先到 TaoToken 控制台创建 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewriteAPI 基础地址统一用https://taotoken.net/api这个地址不加 UTM 参数直接写进代码。项目目录建议这样组织和 SKILL 打包结构对齐skill_life_assistant/ ├── config.toml ├── settings.json ├── skill_core/ │ ├── __init__.py │ ├── llm_client.py │ ├── intent_router.py │ └── template_render.py ├── templates/ │ ├── reminder.tpl.md │ └── recipe.tpl.md └── scripts/ └── reminder_parser.pyconfig.toml放模型与接口配置settings.json放运行时参数超时、重试、场景开关。两者分离的好处是换模型不动业务代码调参数不动密钥。3. 可复制配置config.toml 与 settings.json 骨架3.1 config.toml# config.toml [llm] base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 timeout 30 max_retries 2 [llm.models] # 意图识别用轻量模型响应快、成本低 intent gpt-4o-mini # 内容生成用能力更强的模型 generate gpt-4o [skill] name life_assistant version 0.1.0 # 场景路由表键名与 intent_router 中的枚举一致 scenes [reminder, recipe, travel, health, gift, schedule] [skill.template] dir templates encoding utf-83.2 settings.json{ runtime: { log_level: INFO, save_raw_response: false, fallback_scene: reminder }, intent: { confidence_threshold: 0.6, max_candidates: 3 }, template: { strict_mode: true, missing_param_action: ask_user }, safety: { mask_phone: true, mask_id_card: true, health_disclaimer: true } }confidence_threshold是意图识别的兜底阈值低于 0.6 就不硬猜走fallback_scene或反问用户。strict_mode为 true 时模板里缺参数直接报错而不是留空这在评审时能体现工程严谨性。3.3 读取配置的 Python 代码# skill_core/llm_client.py import json import tomllib from pathlib import Path from openai import OpenAI def load_config(config_path: str config.toml) - dict: with open(config_path, rb) as f: return tomllib.load(f) def load_settings(settings_path: str settings.json) - dict: with open(settings_path, r, encodingutf-8) as f: return json.load(f) class LLMClient: def __init__(self, config: dict): self.cfg config[llm] self.client OpenAI( base_urlself.cfg[base_url], api_keyself.cfg[api_key], timeoutself.cfg.get(timeout, 30), max_retriesself.cfg.get(max_retries, 2), ) def chat(self, model_key: str, messages: list, temperature: float 0.3) - str: model self.cfg[models][model_key] resp self.client.chat.completions.create( modelmodel, messagesmessages, temperaturetemperature, ) return resp.choices[0].message.content注意base_url结尾不要带/v1OpenAI SDK 会自己拼路径。如果你之前用的是别的写法这里是最容易 404 的地方。4. 意图识别与模板渲染从对话输入到服务响应4.1 意图识别让模型输出结构化 JSON关键词匹配在“明天下午三点”这种表达上必挂。正确做法是让模型做分类并且强制输出 JSON这样 Python 侧可以直接解析。# skill_core/intent_router.py import json from .llm_client import LLMClient SCENE_PROMPT 你是一个意图分类器。把用户输入归类到以下场景之一 - reminder: 提醒、日程、闹钟 - recipe: 菜谱、食材、做饭 - travel: 出行、旅游、路线 - health: 健康、减重、运动 - gift: 礼物、送礼 - schedule: 会议、办公、文档 只输出 JSON格式 {scene: 场景名, confidence: 0.0-1.0, slots: {参数名: 参数值}} 用户输入{user_input} def route_intent(client: LLMClient, user_input: str, threshold: float 0.6) - dict: prompt SCENE_PROMPT.format(user_inputuser_input) raw client.chat(intent, [{role: user, content: prompt}], temperature0.0) raw raw.strip().removeprefix(json).removesuffix().strip() try: result json.loads(raw) except json.JSONDecodeError: return {scene: reminder, confidence: 0.0, slots: {}, error: parse_failed} if result.get(confidence, 0) threshold: result[need_clarify] True return resultslots字段是关键它把“明天下午三点”这类自然语言时间原样带出来交给后面的reminder_parser.py做确定性解析。模型负责理解脚本负责精确计算这个分工是 SKILL 稳定的核心。4.2 参数化模板占位符 严格校验模板文件用{{参数名}}占位渲染前先校验参数是否齐全。!-- templates/reminder.tpl.md -- ## 提醒已创建 - 事项{{task}} - 时间{{time_iso}} - 重复{{repeat}} 到点我会提醒你。# skill_core/template_render.py import re from pathlib import Path PLACEHOLDER re.compile(r\{\{(\w)\}\}) def render_template(tpl_path: str, params: dict, strict: bool True) - str: text Path(tpl_path).read_text(encodingutf-8) required set(PLACEHOLDER.findall(text)) missing required - set(params.keys()) if missing and strict: raise ValueError(f模板缺少参数: {missing}) for key in required: text text.replace({{ key }}, str(params.get(key, ))) return text4.3 时间解析脚本确定性逻辑不交给模型# scripts/reminder_parser.py import re from datetime import datetime, timedelta WEEKDAY_MAP {一: 0, 二: 1, 三: 2, 四: 3, 五: 4, 六: 5, 日: 6} def parse_time(text: str, now: datetime None) - str: now now or datetime.now() # 绝对时刻下午3点 / 15:30 m re.search(r(上午|下午|晚上)?(\d{1,2})[:点](\d{1,2})?, text) if m: hour int(m.group(2)) minute int(m.group(3)) if m.group(3) else 0 period m.group(1) if period in (下午, 晚上) and hour 12: hour 12 target now.replace(hourhour, minuteminute, second0, microsecond0) if target now: target timedelta(days1) return target.isoformat() # 相对日明天/后天 if 后天 in text: return (now timedelta(days2)).replace(hour9, minute0).isoformat() if 明天 in text: return (now timedelta(days1)).replace(hour9, minute0).isoformat() # 星期偏移下周三 m re.search(r下周([一二三四五六日]), text) if m: target_wd WEEKDAY_MAP[m.group(1)] days_ahead (target_wd - now.weekday() 7) % 7 7 return (now timedelta(daysdays_ahead)).replace(hour14, minute0).isoformat() raise ValueError(f无法解析时间: {text}) if __name__ __main__: print(parse_time(明天下午3点提醒我买菜))跑一下这个脚本输出类似2026-08-07T15:00:00说明确定性解析没问题。5. 验证请求跑通完整链路5.1 端到端测试脚本# main.py from skill_core.llm_client import load_config, load_settings, LLMClient from skill_core.intent_router import route_intent from skill_core.template_render import render_template from scripts.reminder_parser import parse_time def handle(user_input: str): config load_config() settings load_settings() client LLMClient(config) intent route_intent(client, user_input, settings[intent][confidence_threshold]) print(意图识别结果:, intent) if intent[scene] reminder: slots intent.get(slots, {}) time_iso parse_time(slots.get(time, user_input)) params { task: slots.get(task, 未命名事项), time_iso: time_iso, repeat: slots.get(repeat, 不重复), } return render_template(templates/reminder.tpl.md, params) return f暂未支持场景: {intent[scene]} if __name__ __main__: print(handle(明天下午3点提醒我买菜))5.2 预期输出意图识别结果: {scene: reminder, confidence: 0.92, slots: {time: 明天下午3点, task: 买菜}} ## 提醒已创建 - 事项买菜 - 时间2026-08-07T15:00:00 - 重复不重复 到点我会提醒你。看到这个输出说明对话输入 → 意图识别 → 参数解析 → 模板渲染整条链路已经通了。如果意图识别返回的slots里没有time检查一下 prompt 里的 JSON 格式示例是否被模型正确遵循。5.3 用模型对话快速验证意图识别质量在正式接入前可以先用模型对话页面手动测几条边界输入比如“下周三下午两点开会”“三小时后提醒我取快递”看分类和槽位抽取是否稳定模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite这一步能帮你快速判断 prompt 是否需要加 few-shot 示例比反复改代码快得多。6. 本篇常见错排查6.1 401 或鉴权失败最常见原因是api_key里带了多余空格或者base_url写成了带/v1的地址。检查config.toml中base_url https://taotoken.net/api不要手动加路径。如果 Key 是从控制台复制的注意前后不要有换行。6.2 意图识别返回非 JSON模型有时会输出带解释的文字。两个处理一是 prompt 里明确“只输出 JSON不要任何解释”二是代码里做removeprefix(json)清洗。如果仍然失败把temperature设为 0.0并在 prompt 里给一个完整的输出示例。6.3 时间解析结果差一天parse_time里有个判断如果解析出的时刻已经过了当前时间就加一天。测试时如果用固定时间戳注意传入now参数否则会受运行时刻影响。建议在单元测试里显式传nowdatetime(2026, 8, 6, 10, 0)。6.4 模板渲染报缺少参数strict_mode为 true 时模板里出现的每个{{}}都必须有对应参数。排查方法打印PLACEHOLDER.findall(text)的结果和params.keys()做差集。如果某个参数确实可选在模板里给它一个默认值或者把strict_mode设为 false。6.5 长时间编码任务想省心如果你后续要把这个 SKILL 扩展成持续迭代的编码项目或者接入 Agent 做多轮对话单次调用按量计费可能不够划算。可以了解一下 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite6.6 接入文档与 SDK 细节OpenAI SDK 的兼容细节、流式输出、错误码对照都在接入文档里接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你用的是 Claude Code 这类工具做辅助开发Anthropic 兼容配置也有对应说明ClaudeCodeAnthropichttps://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite7. 把 SKILL 打包前的最后检查在提交讯飞AI开发者大赛之前按这个清单过一遍config.toml里的 Key 是否已替换成环境变量读取不要硬编码提交settings.json的confidence_threshold是否根据你的场景调过scripts/下每个 Python 文件是否都能python xxx.py直接跑出结果模板文件里的占位符是否和intent_router输出的slots键名完全一致。最后一步验证用三条不同场景的输入各跑一次main.py确认意图路由没有串场景模板渲染没有缺参数。跑通之后这套结构可以直接复用到智慧生活助理、教育智能辅助、智能办公协同助理三个子赛道只需要替换templates/和对应的解析脚本。
