DeepSpace 实践指南：用本地代理调试 DeepSeek API 请求

DeepSpace 实践指南用本地代理调试 DeepSeek API 请求【免费下载链接】awesome-deepseek-integrationIntegrate the DeepSeek API into popular software项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-integration本文围绕 docs/deepspace/README.md 展开介绍社区开源工具 DeepSpace 的完整用法它如何以本地 HTTP 代理的形态接管你代码中的base_url完整记录发往 DeepSeek API 的每一次请求与响应并支持按request_id/chatcmpl_id检索、导出 BadCase 上报。读完本文你将掌握 DeepSpace 的两种安装方式、六个子命令的用途以及在代码开发调试阶段将 DeepSpace 作为 DeepSeek API 供应商进行排障的完整工作流。DeepSpace 是什么给 DeepSeek API 调用装一台记录仪DeepSpace 是一款由社区开发、面向 DeepSeek API 调试场景的命令行工具设计灵感来自 Moonshot AI 的开源调试工具 MoonPalace。它不是又一个 API 封装 SDK而是运行在本地、位于你的应用程序与 DeepSeek API 之间的代理服务器你只需把代码里的base_url指向 DeepSpace 监听的本机端口所有请求就会先经过 DeepSpace 被完整记录下来再转发到 DeepSeek。官方将其核心能力概括为以下五点全平台支持Mac、Windows、Linux 均有可用版本简单易用启动服务后只需把base_url替换为http://localhost:9988即可开始调试无需改动业务代码逻辑捕获完整请求包括网络错误时的事故现场完整的错误细节方便定位是代码问题、网络问题还是模型侧问题快速检索通过request_id、chatcmpl_id快速检索并查看历史请求信息一键导出 BadCase 结构化上报数据将不符合预期的模型输出连同请求上下文一并结构化导出帮助 DeepSeek 完善模型能力。官方还给出了一个非常明确的定位建议在代码编写和调试阶段推荐直接把 DeepSpace 当作你的 API 供应商。这样API 调用与代码实现中的各种问题参数拼错、鉴权失败、超时、限流、格式异常等都能在本地被快速发现和定位而当 DeepSeek 大模型出现不符合预期的输出时也可以通过 DeepSpace 导出请求详情并提交给 DeepSeek用于改进模型。安装 DeepSpace两条路径任选方式一使用go命令安装如果本机已经安装 Go 工具链一条命令即可完成安装$ go install github.com/2404589803/deepspacelatest该命令会把编译好的二进制文件安装到$GOPATH/bin/目录。运行deepspace验证是否安装成功若成功会输出命令帮助信息$ deepspace DeepSpace is a command-line tool for debugging the DeepSeek AI HTTP API Usage: deepspace [command] Available Commands: cleanup Cleanup DeepSeek AI requests completion Generate the autocompletion script for the specified shell export Export a DeepSeek AI request help Help about any command inspect Inspect the specific content of a DeepSeek AI request list Query DeepSeek AI requests based on conditions start Start the DeepSpace proxy server Flags: -h, --help help for deepspace -v, --version version for deepspace Use deepspace [command] --help for more information about a command.如果系统提示找不到deepspace命令说明$GOPATH/bin/目录尚未加入$PATH环境变量把该目录追加到$PATH后重新打开终端即可。方式二从 Releases 页面下载预编译二进制如果没有 Go 工具链也可以直接从 DeepSpace 的 Releases 页面下载对应平台的编译产物按需选择文件名适用平台deepspace-linuxLinuxdeepspace-macos-amd64Intel 芯片的 Macdeepspace-macos-arm64Apple SiliconM 系列芯片的 Macdeepspace-windows.exeWindows下载后将二进制放置到任意目录并加入PATHLinux/macOS 下注意先赋予可执行权限即可像方式一一样在终端直接调用。命令行总览六个子命令从deepspace的帮助输出可以完整看到这款 CLI 的能力边界下表对应实际功能子命令作用start启动 DeepSpace 本地代理服务器接管后续请求list按条件查询 DeepSeek AI 请求记录inspect查看某条 DeepSeek AI 请求的具体内容export导出一条 DeepSeek AI 请求cleanup清理删除DeepSeek AI 请求记录completion为指定 shell 生成自动补全脚本help查看任意命令的帮助其中list、inspect、export、cleanup组合起来构成了对已捕获请求从检索、查看、导出到清理的完整管理链路。每个子命令还支持更细粒度的参数运行时可用deepspace [command] --help查看这也是 CLI 帮助文本最后一行给出的提示。启动代理服务并接管base_url启动 DeepSpace 代理服务器使用start子命令$ deepspace start --port PORTDeepSpace 会在本地启动一个 HTTP 服务器--port参数指定 DeepSpace 监听的本地端口默认值为9988不传时即监听该默认端口。启动成功后终端会输出类似下面这样的一行日志[DeepSpace] 2024/08/26 12:12:26 DeepSpace Starts change base_url to http://127.0.0.1:9988/v1这行日志同时是如何接入的明确指引把业务代码中所有指向 DeepSeek 官方端点的base_url改成日志给出的http://127.0.0.1:9988/v1DeepSeek 的 API 与 OpenAI 兼容路径结构同样是/v1前缀其余代码无需改动。之后你的应用发出的每个请求都会先进入 DeepSpace 的记录视野再被代理转发到 DeepSeek 真实服务你在调试期的供应商从云端变成了这台本地记录仪。由于日志默认输出http://127.0.0.1:9988/v1而不是localhost如果你在远程或容器场景需要别的监听地址可留意对应版本start子命令的帮助参数按需指定端口与监听行为。请求检索与事故现场还原list / inspect代理服务器一旦运行、应用请求开始经过它DeepSpace 就会持续积累请求记录。当你想复盘某次调用时可以借助两个检索维度——request_id与chatcmpl_idchatcmpl_id来自 OpenAI 兼容的 Chat Completions 接口响应体中的id字段通常形如chatcmpl-…是会话补全结果本身的唯一标识request_id一般指 HTTP 层面的请求唯一标识可用于精确锁定某一次实际发出的调用。典型排查动线如下先用deepspace list按条件如时间、模型、ID 等筛选出可疑的请求记录拿到目标request_id/chatcmpl_id再用deepspace inspect查看该请求的具体内容——请求参数、响应结果以及出现网络故障时的完整错误细节。这一步的价值在于还原事故现场很多调用失败发生在网络层超时、连接被重置、TLS 异常等应用侧 SDK 通常只能收到一个笼统的异常。而经过 DeepSpace 后请求与错误详情被原样保留下来你就能区分问题是出在自己的代码、网络环境还是 DeepSeek 服务侧从而快速定位和解决 API 调用相关的问题。导出 BadCase 上报export / cleanup排查过程中如果确认是DeepSeek 大模型输出不符合预期而非代码或网络问题可以把该请求作为 BadCase 导出提交给 DeepSeek 用于改进模型用deepspace inspect确认目标请求的上下文与输出确实属于模型侧问题用deepspace export一键导出该请求——DeepSpace 会将其整理为BadCase 结构化上报数据请求参数、模型输出、期望差异等关键信息被打包为便于官方处理的格式将导出的文件投递至官方反馈邮箱api-servicedeepseek.com。历史请求记录积累过多时可以使用deepspace cleanup清理无用的旧请求让检索列表保持干净。整体上看list → inspect → export → cleanup是一条从发现问题到证据归档再到现场清理的完整闭环。推荐的开发调试工作流把前面几节串起来一个推荐的 DeepSeek API 集成调试工作流如下启动记录仪运行deepspace start默认端口 9988确认看到DeepSpace Starts日志切换供应商把代码中 DeepSeek 的base_url改为http://127.0.0.1:9988/v1开始正常的开发与调试复现问题运行你的程序触发 API 调用让请求经过 DeepSpace 被完整记录检索定位调用出错时用deepspace list结合request_id/chatcmpl_id锁定请求用deepspace inspect查看完整请求、响应与错误细节快速判断问题归属归档或上报属于模型输出质量问题的用deepspace export导出 BadCase 并发往api-servicedeepseek.com其余历史记录按需用deepspace cleanup清理。值得一提的是本仓库 收录了大量将 DeepSeek API 集成进各类软件的方案当你在开发、接入或调试其中任何一款客户端时把 DeepSpace 作为开发期的统一本地端点都能在不改动上层业务逻辑的前提下获得全量请求可见、问题一键定位、BadCase 一键导出的调试体验。更完整的中文说明可参见同目录下的 docs/deepspace/README_cn.md各子命令的详细参数以本地运行deepspace [command] --help的输出为准。【免费下载链接】awesome-deepseek-integrationIntegrate the DeepSeek API into popular software项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-integration创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考