搞懂AI

简体中文

English

简体中文

English

Appearance

🚀 快速起步第 6 / 6 节

装不上跑不通怎么办：起步排错 ​

第一个请求跑不通，八成卡在三处：环境装错了 Python、Key 没配好、请求体不合规则。这节课把常见 TypeSafe 报错按「报错原文」逐个给原因和解法——先 60 秒速检，再对号入座。所有 Python 报错都在 typesafe-sdk v0.7.5、Python 3.12 上实际复现过。

学完你能做什么 ​

  • 用 3 条命令在 60 秒内定位环境、Key、网络哪一环出了问题
  • 把 TypeSafe 报错对号入座：装在哪个环节、什么原因、怎么修
  • 读懂 7 个 HTTP 状态码（400/401/413/415/422/429/529）各自在说什么
  • 在代码里用 except TypeSafeAPIError 打印 status 和 request_id，给提问时带上证据
  • 知道去哪求助：控制台、官方文档、GitHub Issues、Discord

你现在的困境 ​

  • pip 装完了，一运行就 ModuleNotFoundError——是没装上、用错 Python，还是装了个同名的错包？
  • Key 明明设置了，还是 401，来回重抄了三遍
  • 报错信息是一坨 JSON，看不懂哪个字段才是问题所在

什么时候用这一招 ​

当你需要：

而且不想：

  • 报错就去论坛发帖等回复，60 秒速检能省掉大部分等待
  • 分不清「代码错了」和「Key/额度/服务端的问题」，白改半天代码

🎒 开始前的准备 ​

  • 跑过 安装与第一个请求（卡住没关系，本课就是解卡的）
  • 终端能用 Bash（macOS / Linux / Windows WSL——官方命令按这个环境写）
  • 一个已登录 TypeSafe 控制台 的浏览器（Key 相关问题要回去看）

核心思路 ​

先定位环节，再看报错。 一次 Jev 调用要过四关，每关的报错长得不一样：

关卡检查什么典型报错
1. 环境Python 版本、包装没装对ModuleNotFoundError
2. 认证Key 有没有、对不对401 / 403（直连没带认证头，实测）/ TypeSafeError（创建客户端就抛）
3. 请求体JSON 规则、问题定义400 / 422
4. 服务端限流、过载429 / 529

SDK 会把一部分错误拦在本地。 v0.7.1 起，无效 Key 在创建客户端时就抛 TypeSafeError，请求根本不发出去；问题定义缺 criteria 也是本地拦截。所以同样是 TypeSafeError，有的根本没到服务器——先分清「本地拦截」和「服务器返回」，排错方向完全不同。

状态码一览。 服务器返回的错误带标准 HTTP 状态码（docs/api/errors.md）：

状态码意思一句话
400 Bad Request违反请求规则（UTF-8、嵌套层数、非有限数字、坏压缩体）；max_tokens_exceeded = 超上下文改请求体
401 UnauthorizedKey 缺失或无效查 Key
413 Payload Too Large请求体超 32 MiB减体积
415 Unsupported Media TypeContent-Encoding 不支持或压缩超一层改压缩
422 Unprocessable Entity字段校验失败，body 指明字段补字段
429 Too Many Requests超速率限制退避重试
529 OverloadedTypeSafe 临时过载退避重试

💡 带上 request_id 去提问

SDK 的 API 错误对象有 request_id（来自 x-typesafe-request-id 响应头）。给官方反馈时带上它，对方能直接查到那次请求。Discord 社区入口：discord.gg/typesafe。

首次排查：60 秒速检 ​

三条命令按顺序跑，依次验证包、Key、网络与认证，每条都标了预期输出。

bash
# 1. 包装对了吗？——应该看到 0.7.5（或更高）
.venv/bin/python -c "import typesafe_sdk; print(typesafe_sdk.__version__)"
# 若报 ModuleNotFoundError：装的环境和跑的环境不是同一个，或装错了包（见下方排错）

# 2. Key 设置了吗？——应该看到完整 Key 字符串
echo "$TYPESAFE_API_KEY"
# 空的：export TYPESAFE_API_KEY="your-api-key" 再跑（新开终端要重新 export）

# 3. Key 真的有效吗？——应该看到 HTTP 401（说明网络通、你还没用真 Key）
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"
# 200 = 认证通过；401 = Key 无效（见下方排错）

你应该看到：第 1 条打印版本号、第 2 条打印 Key、第 3 条返回 200（Key 有效时）或可辨认的状态码。哪条断了就从哪条修。

常见问题排查 ​

环境与安装问题 ​

"ModuleNotFoundError: No module named 'typesafe_sdk'" ​

原因：包装进了 .venv，但运行用的是系统 Python（或另一个环境）——两边的解释器不是同一个。另一种可能：pip install typesafe 装了个同名的错包（见下一节）。

解决：

  1. 始终用 venv 里的解释器运行（官方示例的写法）：
bash
.venv/bin/python route_ticket.py
  1. 或者先激活环境再运行（通用 venv 用法）：
bash
source .venv/bin/activate
python route_ticket.py
  1. 还不行就确认包真的装上了：重新执行 .venv/bin/pip install typesafe-sdk，看输出里 Successfully installed。

你应该看到：三行输出 technical / 0.67 / 0.99（数值随版本变化，结构对即可）。

"ImportError: cannot import name 'TypeSafeClient' from 'typesafe'" ​

原因：pip install typesafe（少写 -sdk）不会报错——它装上的是同名的无关第三方库 typesafe 0.9.1（"formal type asserting decorators"，作者 Krister Hedfors，与 TypeSafe AI 没有任何关系），里面自然没有 TypeSafeClient。于是 from typesafe import TypeSafeClient 抛 ImportError；同一环境里 import typesafe_sdk 则抛上面的 ModuleNotFoundError。

解决：

  1. 卸载装错的包，装正确的包（安装名是连字符 typesafe-sdk）：
bash
.venv/bin/pip uninstall -y typesafe
.venv/bin/pip install typesafe-sdk
  1. 验证 import（import 名是下划线 typesafe_sdk）：
bash
.venv/bin/python -c "from typesafe_sdk import TypeSafeClient; print('ok')"

你应该看到：ok；pip 输出含 Successfully installed ... typesafe-sdk-0.7.5。

Python 版本低于 3.10 ​

原因：官方 SDK 要求 Python 3.10 或更高（docs/introduction/quickstart.md："Requires Python 3.10 or later"，PyPI 元数据 requires-python = ">=3.10"）。

解决：

  1. 查当前版本：
bash
python3 --version
  1. 版本低于 3.10：安装 3.10+ 后用它重建 venv（旧 venv 绑定旧解释器，必须重建）：
bash
python3.10 -m venv .venv   # 或你装好的更高版本
.venv/bin/pip install typesafe-sdk

你应该看到：.venv/bin/python --version 打印 Python 3.10 或更高。

"zstd compression requires Python 3.14+ or the typesafe-sdk[zstd] extra." ​

原因：你显式传了 compression='zstd'，但 Python < 3.14 时 zstd 支持在可选 extra 里，默认安装不带。

解决（两个方案）：

方案 1（装 extra，推荐）：

bash
.venv/bin/pip install "typesafe-sdk[zstd]"

方案 2（关闭压缩）：

python
client = TypeSafeClient(compression=False)

⚠️ v0.7.5 默认开压缩

v0.7.5 起 SDK 默认用 zstd 压缩 ≥1 KiB 的请求体（官方 changelog 标注：非官方 API 可能不会立即支持）。官方要求「确保 zstd 可用」的命令是 uv add "typesafe-sdk[zstd]"。实测默认安装（不带 extra）在对象创建时不报错——压缩可用就用、不可用就不压缩，只有显式要求 zstd 才会抛这个错。

"ImportError: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using pip install httpx[socks]." ​

原因：环境里配了 SOCKS 代理（代理环境变量），SDK 的 HTTP 层（httpx2）走 SOCKS 需要 socksio 包，默认安装不带——创建客户端时就抛这个错，请求发不出去。

解决：装上 socksio 再重建客户端：

bash
.venv/bin/pip install socksio

你应该看到：客户端创建成功（实测：装上 socksio 后，同样带着 SOCKS 代理，客户端正常创建）。报错信息里建议的 pip install httpx[socks] 是 httpx 系的通用提示；SDK 用的是 httpx2，直接装 socksio 就够。

pip 装不上 / 找不到包（网络类） ​

原因：官方文档未提供 TypeSafe 专用的安装失败方案；常见情况是到 PyPI 源站网络不通，或包名拼错装成了别的包（见上）。

解决：

  1. 先排除包名问题：正确命令是 pip install typesafe-sdk，装对时输出含 Successfully installed ... typesafe-sdk-0.7.5。
  2. 网络问题按你的环境处理（代理、镜像源属通用 pip 知识，官方文档未给 TypeSafe 专用方案）。
  3. Python < 3.10 时 pip 可能直接拒绝安装（官方最低版本 3.10），先按上一条修版本。

认证与 Key 问题 ​

"No API key was provided. Pass api_key or set the TYPESAFE_API_KEY environment variable." ​

原因：既没传 api_key 参数，也没设环境变量——SDK 在创建客户端时就拦下了。注意：显式传空 Key 不会回落到环境变量，api_key='' 等同没传。

解决：

  1. 环境变量方案（官方推荐，代码里不写密钥）：
bash
export TYPESAFE_API_KEY="your-api-key"
  1. 或在代码里显式传参：
python
from typesafe_sdk import TypeSafeClient

client = TypeSafeClient(api_key="your-api-key")

你应该看到：客户端创建成功，不再抛 TypeSafeError。

"Cannot authenticate with the server. Please check your API key and try again." ​

原因：HTTP 401——请求到了服务器，但 Key 无效。SDK 抛 TypeSafeAuthenticationError（str(e) 形如 POST https://api.typesafe.ai/v1/systemone: 401 Cannot authenticate... (request_id=req_...)）。

解决：

  1. 回 控制台 Keys 页 重新复制一遍 Key（手抄容易错）。
  2. 重新设置并验证：
bash
export TYPESAFE_API_KEY="<重新复制的Key>"
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

你应该看到：命令返回 200 和一个 JSON（{"models":[...]}，列出你的账号可用的模型与别名）。

"Must supply an API key! Check your request and try again." ​

原因：直连 HTTP（curl / fetch）时完全没带 Authorization 头——API 直接拒绝并返回 403（实测：不带任何认证头请求 /v1/models，得到 403 和这条消息；官方状态码表未列 403，SDK 侧对应的异常类是 TypeSafePermissionDeniedError）。SDK 用户一般碰不到：Key 配好时 SDK 自动带头。

解决：带上 Bearer 认证头再发：

bash
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

你应该看到：Key 有效时返回 200 和 {"models":[...]}；Key 无效时变成 401（见上一条）。

"API key must contain only printable ASCII characters without whitespace." ​

原因：Key 里有内部空格、控制字符或非 ASCII 字符（SDK 只剥首尾空白，内部的问题字符直接拒收）。

解决：重新完整复制 Key，不要拼接或手改。粘贴时注意别混入换行到中间。

请求体被拒（400 / 413 / 415 / 422） ​

"422 Unprocessable Entity" ​

原因：请求体字段校验失败——比如缺 state、字段格式不对。请求过了 SDK 的本地校验、发到服务器后，由服务器返回 422；响应 body 会指明字段：loc 是位置，msg 是原因（如 Field required）。

解决：

  1. 在代码里捕获 TypeSafeAPIError，打印完整 body 看字段（示例里的问题带了 instructions，能通过本地校验、真正发到服务器）：
python
from typesafe_sdk import Noul, TypeSafeClient, TypeSafeAPIError

with TypeSafeClient() as client:
    try:
        client.system_one("I was charged twice.", {
            "billing": Noul(instructions="Is this about billing?")
        })
    except TypeSafeAPIError as error:
        print(error.status)        # 服务器返回的状态码；422 = 字段校验失败
        print(error.body)          # 422 时里边 loc/msg 指明哪个字段
        print(error.request_id)    # 反馈给官方时带上
  1. 按 loc 指出的字段补齐再发。

你应该看到：请求合法时正常返回结果；若服务器返回 422，error.body 里是形如 loc: ["body", "state"]、msg: "Field required" 的字段级提示（官方 OpenAPI 示例）。服务端 422 的具体触发形态取决于请求违反了哪条规则，以 body 实际返回为准。

💡 很多 422 根本到不了服务器

构造 Noul() 时少写 instructions，SDK 本地就抛 TypeSafeError: Noul question "q2" has neither instructions nor criteria; at least one is required.；Score/Choice 题缺 criteria 同样本地拦截：TypeSafeError: Question "broken" requires "criteria".（broken 处是你自己的问题键名）。这类抛的是 TypeSafeError 基类、不是 TypeSafeAPIError——改代码就行，不用怀疑网络。

"413 Payload Too Large" ​

原因：请求体超过 32 MiB（header 不算在内）；压缩后的和解压后的都受这个限制。

解决：裁剪 state，或把大材料拆成多次请求。

"415 Unsupported Media Type" ​

原因：Content-Encoding 用了不支持的编码，或压缩叠了不止一层（gzip / x-gzip / zstd 各只能一层）。

解决：直连 HTTP 时只用一层压缩；SDK 用户一般碰不到（SDK 自己处理压缩）。

"max_tokens_exceeded" ​

原因：请求超过了模型的上下文限制——64k per-request（state + 所有问题）/ 32k per-question（state + 单个问题），都含 state。

解决（三个方案，按代价从低到高）：

方案 1（裁剪材料，推荐）：过滤 state，只发该题需要的字段——既省钱又提准。

方案 2（长上下文）：给需要的请求加请求头（两个上下文都变 262k，更慢更不准，价格不变）：

bash
-H "TypeSafe-Danger-Zone-Long-Context: true"

方案 3（减少问题数或拆请求）：per-request 限制含所有问题，问题太多先拆。

限流与服务端问题 ​

"429 Too Many Requests" ​

原因：超出了组织级速率限制（tokens/s + requests/s 双指标，按组织计）。

解决：

  1. 用 SDK（默认就带指数退避重试，并遵循 retry-after）——你什么都不用做：
python
from typesafe_sdk import RetryPolicy, TypeSafeClient

# 默认就是自动重试；按需自定义（默认 max_retries=2、退避 0.5→5s、总预算 30s）
client = TypeSafeClient(retry=RetryPolicy(max_retries=3))
  1. 直连 HTTP 才要自己写指数退避，别立刻原样重发。
  2. 额度在 控制台 rate-limits 页 查；需要更高走 custom/enterprise（申请表 support.typesafe.ai/forms/rate-limit-increase-request）。

"529 Overloaded" ​

原因：TypeSafe 临时过载，和 429 一样属于「稍等再试」类。

解决：同 429——SDK 自动退避重试；直连自己写退避。持续出现就去 Discord 或状态页看看是不是大面积故障。

Agent Skill 相关问题 ​

"The agent isn't using the skill" ​

原因：coding agent 没加载 TypeSafe skill——没点名调用、装错了 agent，或装完没重启。

解决（docs/agent-skill.md 官方三步）：

  1. Claude Code 插件里直接调 /typesafe:typesafe-ai；其他 agent 在 prompt 里点名 "use the TypeSafe skill"。
  2. 还不行：确认安装时选的就是你在用的这个 agent（npx skills add 默认装项目级，装全局加 -g）。
  3. 重启 agent 再试。

"The agent invents request or response fields" ​

原因：skill 版本过期，教它的是旧接口。

解决：更新 skill 后重试（Claude Code）：

bash
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai

然后重启 Claude Code 或运行 /reload-plugins。

还是不行？ ​

先收集证据再提问。 一段能复现的最小代码 + 报错原文 + request_id，比一百句描述都管用：

python
# catch_report.py：复现问题并打印关键信息
from typesafe_sdk import Noul, TypeSafeClient, TypeSafeAPIError

with TypeSafeClient() as client:
    try:
        client.system_one("I was charged twice.", {
            "billing": Noul(instructions="Is this about billing?")
        })
    except TypeSafeAPIError as error:
        print("status:", error.status)
        print("body:", error.body)
        print("endpoint:", error.endpoint)
        print("request_id:", error.request_id)  # 提问必带
    except Exception as error:  # 本地拦截（Key/问题定义），没到服务器
        print(type(error).__name__, str(error))

需要更细的日志时，把 SDK 日志级别调高（认证头会脱敏，但请求/响应体不脱敏——注意别把敏感内容发到公开场合）：

bash
export TYPESAFE_LOG_LEVEL=debug

去哪里问：

渠道什么时候去
控制台 Keys / rate-limits 页Key 与额度类问题，先自查
官方报错文档状态码语义与规则细节
API 速查本站：请求/响应/状态码速查
GitHub IssuesSDK 缺陷（Python SDK 仓库）
Discord 社区官方说「Tell us what you build, and what breaks」——坏了直接报

检查点 ✅ ​

  • 60 秒速检三条命令我都跑过，知道卡在哪一关
  • 我能分清本地拦截的 TypeSafeError（Key、问题定义）和服务器返回的 TypeSafeAPIError
  • 401 时我会回控制台重抄 Key，再用 curl /v1/models 验证
  • 429/529 我知道 SDK 默认自动退避重试，不用自己写
  • 提问时我会带上最小复现代码和 request_id

本课小结 ​

✅ 排错先定环节：环境（Python/包）→ 认证（Key）→ 请求体（规则）→ 服务端（限流/过载）。

✅ 关键 TypeSafe 报错都过了：ModuleNotFoundError 用对解释器、401 重抄 Key、422 看 loc 字段、429/529 交给 SDK 默认重试。

✅ 提问姿势：最小复现 + 报错原文 + request_id，去 Discord 或 GitHub Issues。

关键事实回顾：

信号在哪一层第一步
ModuleNotFoundError环境用 .venv/bin/python 运行
ImportError: cannot import name 'TypeSafeClient' from 'typesafe'环境（装错包）卸载 typesafe，改装 typesafe-sdk
创建客户端抛 TypeSafeError认证（本地）补 TYPESAFE_API_KEY
401 + TypeSafeAuthenticationError认证（服务器）回控制台重抄 Key
422请求体看 body 的 loc/msg
429 / 529服务端交给 SDK 重试；直连写退避

下一课预告 ​

起步排错到此收工——你的环境已经稳了。下一步进入 日常使用：掌握 Jev 的五种提问方式。

你会学到：

  • State 状态：给 Jev 什么样的材料
  • Choice / Score / Noul 三种题型怎么选
  • Confidence 置信度怎么用阈值做分支
  • 图像怎么发进请求

相关教程 ​

搞懂AI关于我们怎么写隐私说明

独立的第三方教程，与文中提到的任何产品及其公司没有隶属或合作关系；产品名称和商标归各自所有者。价格和政策以官方页面为准。