DeepSeek-R1-Distill-Qwen-1.5B实战案例：用它生成API文档+Postman测试用例

1. 引言：当轻量级AI助手遇上开发者的日常

如果你是一名开发者，下面这个场景你一定不陌生：产品经理刚刚和你确认了一个新的API接口需求，你花了半天时间写好了代码，然后……你开始头疼了。你需要写一份清晰易懂的API文档，告诉前端同事怎么调用；你还需要在Postman里配置一堆测试用例，验证接口是否正常。这些工作琐碎、重复，但又必不可少。

今天，我想和你分享一个能帮你从这些重复劳动中解放出来的小工具：一个完全运行在你本地的AI助手。它基于一个叫 DeepSeek-R1-Distill-Qwen-1.5B 的超轻量模型，只有15亿参数，对硬件要求极低，普通笔记本电脑就能跑起来。最关键的是，我把它调教成了一个“开发小助手”，专门用来干两件事：

1. 根据代码或描述，自动生成结构清晰的API文档。
2. 根据API文档或接口信息，一键生成可直接导入Postman的测试用例集合。

这篇文章，我就手把手带你看看，我是怎么把这个小模型用起来的，以及它实际干活的效果到底怎么样。你会发现，给AI一个明确的指令，它真的能成为你开发流程中的得力副驾。

2. 项目核心：一个专为本地部署设计的对话助手

在深入实战之前，我们先快速了解一下驱动这个“开发小助手”的核心引擎。它不是一个复杂的系统，而是一个追求简单、高效和隐私的本地化解决方案。

2.1 模型选择：为什么是DeepSeek-R1-Distill-Qwen-1.5B？

我选择这个模型，主要是看中了它的三个特点，这三点对于打造一个实用的本地工具至关重要：

• 轻量高效：1.5B（15亿）的参数规模，是它最大的优势。这意味着它不需要昂贵的专业显卡，在消费级的GPU甚至性能不错的CPU上都能流畅运行。模型文件大小通常在3GB左右，下载和加载都很快。
• 能力均衡：这个模型是“蒸馏”出来的。你可以把它理解为一个“精华版”，它从更大的教师模型那里学到了核心的逻辑推理和代码理解能力，但体型却小巧了很多。对于生成文档、整理测试用例这种结构化任务，它的能力完全够用。
• 完全本地化：所有对话、所有处理都在你的机器上完成。你写的代码、你的API信息，永远不会离开你的电脑。这对于处理公司内部项目、敏感数据来说，是一个必须考虑的前提。

2.2 工具搭建：Streamlit带来的零门槛交互

为了让这个模型用起来方便，我选择了 Streamlit 来构建交互界面。Streamlit是一个专门为数据科学和机器学习打造的工具，用它写一个Web应用简单得不可思议。

对于这个项目，它的好处很明显：

• 几分钟就能搭出界面：你不需要懂前端（HTML、CSS、JavaScript），用Python写几十行代码，一个包含聊天框、历史记录和按钮的Web界面就出来了。
• 像写脚本一样自然：整个应用的逻辑就是顺序执行你的Python代码，定义好输入框、按钮和显示区域，剩下的交给Streamlit。
• 一键启动和分享：运行一个命令，服务就在本地启动，你可以在浏览器里直接访问。效果如下面这个极简的界面所示：

# 这是一个极度简化的Streamlit聊天应用框架
import streamlit as st

st.title("我的本地开发助手")
# 初始化聊天历史
if "messages" not in st.session_state:
    st.session_state.messages = []

# 显示历史消息
for message in st.session_state.messages:
    with st.chat_message(message["role"]):
        st.markdown(message["content"])

# 聊天输入框
if prompt := st.chat_input("考考DeepSeek R1..."):
    # 将用户输入加入历史并显示
    st.session_state.messages.append({"role": "user", "content": prompt})
    with st.chat_message("user"):
        st.markdown(prompt)

    # 这里是调用本地模型生成回复的逻辑（后续详解）
    with st.chat_message("assistant"):
        response = generate_response(prompt) # 调用模型
        st.markdown(response)
        st.session_state.messages.append({"role": "assistant", "content": response})

有了这个基础，我们就可以专注于最重要的部分：如何让模型理解我们的开发需求，并输出我们想要的结果。

3. 实战演练一：让AI帮你写API文档

好了，背景介绍完毕，我们进入正题。假设我刚写完一个用户登录的API，代码大概是这样的：

# app.py (FastAPI示例)
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class LoginRequest(BaseModel):
    username: str
    password: str

class LoginResponse(BaseModel):
    code: int
    message: str
    data: dict = None

@app.post("/api/v1/auth/login", response_model=LoginResponse)
async def user_login(login_data: LoginRequest):
    """
    用户登录接口。
    验证用户名和密码，成功则返回用户基本信息和访问令牌。
    """
    # 这里应该是数据库验证逻辑，我们简化为一个示例
    if login_data.username == "admin" and login_data.password == "123456":
        return LoginResponse(
            code=200,
            message="登录成功",
            data={"user_id": 1, "username": "admin", "token": "fake_jwt_token_here"}
        )
    else:
        raise HTTPException(status_code=401, detail="用户名或密码错误")

现在，我不想自己手动去写Markdown文档。我打开本地的AI助手，在输入框里给它下达一个清晰的指令：

我的指令： 请为下面的Python FastAPI代码生成一份标准的API接口文档，使用Markdown格式。文档需要包含：接口名称、端点URL、请求方法、请求头、请求体参数说明（表格形式）、成功响应示例、错误响应示例以及可能的注意事项。 代码：[这里粘贴上面的代码]

AI助手的回复（结构化后）：

思考过程：用户提供了一个FastAPI登录接口的代码片段，要求生成Markdown格式的API文档。我需要提取代码中的关键信息：端点路径、HTTP方法、输入输出模型。然后按照常见的API文档结构组织内容，包括概述、请求、响应和示例。特别注意要将LoginRequest和LoginResponse的字段用表格清晰说明。

最终回答：

用户登录接口文档

接口概述

• 接口名称：用户登录
• 功能描述：验证用户凭证（用户名和密码），验证成功则返回用户基本信息和访问令牌。
• 端点URL：/api/v1/auth/login
• 请求方法：POST

请求说明

请求头（Headers）

参数名	类型	是否必填	说明
Content-Type	string	是	必须设置为 application/json

请求体（Body）

请求体需要以JSON格式发送，参数如下：

字段名	类型	是否必填	说明	示例
username	string	是	登录用户名	"admin"
password	string	是	登录密码	"123456"

响应说明

成功响应（HTTP 200）

返回格式为JSON，结构符合LoginResponse模型。

字段名	类型	说明
code	integer	状态码，成功为200
message	string	状态信息
data	object	成功时返回的用户数据对象

data 对象结构：

字段名	类型	说明
user_id	integer	用户唯一ID
username	string	用户名
token	string	用于后续接口认证的JWT令牌

成功响应示例：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": 1,
    "username": "admin",
    "token": "fake_jwt_token_here"
  }
}

错误响应（HTTP 401）

当用户名或密码验证失败时返回。

错误响应示例：

{
  "detail": "用户名或密码错误"
}

注意事项

1. 密码建议在传输前由前端进行加密处理。
2. 返回的token需在后续请求的Authorization请求头中携带（格式如：Bearer <token>）。
3. 此示例代码使用硬编码验证，实际应用中请连接数据库进行凭证校验。

怎么样？虽然生成的内容基于我们给的简单代码，但结构非常清晰，该有的部分都有了：概述、请求头、参数表格、响应结构、示例代码。我只需要花几秒钟检查一下，就可以直接复制这份Markdown文档，贴到项目的README或Wiki里。这比我从头开始敲键盘要快得多，也规范得多。

4. 实战演练二：让AI生成Postman测试用例

有了API文档，下一步就是测试。在Postman里手动配置请求URL、Method、Body……虽然不难，但接口一多也挺烦人。我们继续使唤AI助手。

这次，我可以直接把上面生成的API文档内容丢给它，或者更简单一点，直接描述接口信息。

我的指令： 请根据以下接口信息，生成一个可以导入Postman的Collection（集合）的JSON文件内容。这个Collection命名为“用户认证接口”，里面包含一个“用户登录”请求。 接口信息：

• 名称：用户登录
• 方法：POST
• URL：{{base_url}}/api/v1/auth/login
• 请求头：Content-Type: application/json
• 请求体JSON示例：{"username": "admin", "password": "123456"}
• 成功响应示例：{"code":200, "message":"登录成功", "data":{"user_id":1,"username":"admin","token":"fake_jwt_token"}} 请使用Postman Collection v2.1格式。

AI助手的回复（结构化后）：

思考过程：用户要求生成Postman Collection的JSON数据。我需要按照Postman Collection v2.1的格式来构建一个JSON对象。这个对象需要包含info（集合信息）、item（请求列表）等顶级字段。在item里，要定义请求的name、request（包含method、url、header、body）。其中，body需要设置为raw JSON格式，并填入示例数据。还需要注意使用变量{{base_url}}以便在Postman中灵活配置。

最终回答：

{
  "info": {
    "name": "用户认证接口",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "用户登录",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json",
            "type": "text"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"username\": \"admin\",\n  \"password\": \"123456\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "url": {
          "raw": "{{base_url}}/api/v1/auth/login",
          "host": ["{{base_url}}"],
          "path": ["api", "v1", "auth", "login"]
        }
      },
      "response": []
    }
  ],
  "variable": [
    {
      "key": "base_url",
      "value": "http://localhost:8000",
      "type": "string"
    }
  ]
}

使用步骤：

1. 在电脑上新建一个文本文件，将上面的JSON内容完整复制进去。
2. 将文件保存为 用户认证接口.postman_collection.json。
3. 打开Postman，点击左上角的“Import”按钮。
4. 选择你刚保存的JSON文件，导入即可。

导入后，你会在Postman左侧看到名为“用户认证接口”的集合，点开里面就有一个配置好的“用户登录”请求。你只需要在Postman的环境变量里设置好 base_url（比如你的本地开发地址 http://127.0.0.1:8000），就可以直接点击“Send”进行测试了。

从一段描述到一个可执行的测试用例，只需要一次对话。如果你有十几个接口，这个效率提升是非常可观的。

5. 进阶技巧：如何与AI助手有效沟通

通过上面两个例子，你可能发现了关键：想要AI帮你干好活，你得先学会给它下清晰的指令。这就像和一个新来的、非常聪明的实习生沟通一样。这里我分享几个让这个“开发助手”更好用的技巧：

1. 给它一个明确的角色：在问题开头，先设定它的身份。例如：“你现在是一个资深的后端开发工程师，请帮我...”。这能引导它用更专业的视角来回答问题。
2. 提供充足的上下文：不要只问“怎么生成API文档？”。而是像我做的那样，把代码、数据结构、你的具体要求都给它。信息越全，它的输出越精准。
3. 要求结构化输出：明确告诉它你想要的格式。比如“请用Markdown表格列出参数”、“请生成Postman Collection v2.1格式的JSON”。模型对这类结构化指令的理解通常很好。
4. 分步骤进行复杂任务：如果一个任务很复杂，可以拆解。比如，先让它分析代码中的接口，列出所有端点；再针对每个端点，逐一生成详细的文档。
5. 利用它的“思考过程”：本项目的一个特色是它会输出思考标签。虽然我在展示时做了格式化，但这个原始输出能帮你理解模型是如何拆解你的问题的。如果结果不理想，你可以根据它的“思考”来调整你的提问方式。

6. 总结

回过头来看，我们利用一个可以在本地笔记本上运行的、1.5B参数的小模型，完成了两件开发中的具体工作：生成API文档和创建Postman测试集。整个过程没有联网，没有数据泄露风险，响应速度也很快。

这给我们带来一些启发：

• 轻量化模型足够应对特定场景：对于文档生成、代码补全、测试用例生成这类有明确模式和规则的任务，我们不一定需要动用数百亿参数的大模型。一个精心调教的小模型，在成本和效率上可能更具优势。
• 本地部署是敏感场景的刚需：对于企业开发、处理内部代码和数据结构，能够本地私有化部署的AI工具，其安全性和可控性是不可替代的。
• AI是增强工具，而非替代品：它生成的文档和测试用例，仍然需要开发者进行审核和调整。但它极大地降低了我们从零开始的“冷启动”成本，把我们从重复的格式性工作中解放出来，让我们能更专注于核心的逻辑和架构设计。

这个基于DeepSeek-R1-Distill-Qwen-1.5B和Streamlit的小项目，就像一个概念验证。它展示了如何将前沿的AI能力，以极低的门槛和成本，融入到我们最日常的开发 workflow 中。你不妨也试试，给它一段你的代码，看看它能为你生成什么。也许下一个被你自动化的工作环节，就在眼前。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。