【三个月 AI Agent 实战学习】Day 7 ：阶段总结 —

Day 7：阶段总结 —— 命令行翻译软件实战

欢迎来到第一阶段的最后一天！今天我们将不再学习新概念，而是整合前六天所学，完成一个完整的命令行翻译软件。这个项目将覆盖 API 调用、Prompt 设计（含 JSON 输出、Few-shot 思维）、JSON 解析与重试机制，是一次全面的实战检验。

在这里插入图片描述

一、今日学习目标

综合运用前六天知识：API 调用、结构化输出、错误处理。
实现一个命令行交互程序：用户输入中文或英文，程序自动识别语言并翻译成另一种语言。
强制模型输出 JSON，并在代码中可靠解析。
添加重试机制，确保翻译服务的稳定性。
通过实战加深对 Prompt 工程的理解，并体会“模型输出结构化数据”在真实应用中的价值。

二、详细实现步骤

步骤 1：设计系统架构

我们的命令行翻译软件包含以下模块：

translate(text)：核心翻译函数，接收用户输入，调用大模型，返回解析后的翻译结果字典。
extract_json(raw)：从模型原始输出中提取并解析 JSON 对象（复用 Day 6 的逻辑）。
主循环：不断读取用户输入，调用 translate，打印结果，直到用户输入“退出”。

系统流程：
用户输入 → 调用 API（Prompt 要求输出 JSON）→ 获取原始响应 → 清洗并解析 JSON → 提取翻译结果 → 显示给用户。

步骤 2：编写 Prompt 模板

Prompt 设计如下：

System Prompt：

你是一个专业的翻译助手。你会收到用户输入的一段文本，请自动判断其语言（中文或英文）。如果输入是中文，请将其翻译成英文；如果输入是英文，请将其翻译成中文。如果输入包含其他语言或无法识别，请在 translation 字段中返回错误提示。
你必须只输出一个 JSON 对象，格式如下：
{“detected_language”: “zh” 或 “en”, “target_language”: “en” 或 “zh”, “translation”: “翻译后的文本”}
不要输出任何其他文字。

User Prompt：

请翻译以下文本：
{user_input}

我们将 user_input 插入到 User Prompt 中。注意：如果用户输入包含特殊字符，我们使用 f-string 直接插入即可。

步骤 3：实现核心函数

新建 translator.py，首先导入依赖：

import os
import json
import re
import time
from dotenv import load_dotenv
from openai import OpenAI

加载环境变量和初始化客户端（同前）：

load_dotenv()
client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

定义 JSON 提取函数（复用 Day 6 代码，可稍作优化）：

def extract_json(text: str):
    """从模型输出中提取并解析 JSON 对象"""
    text = text.strip()
    # 去除 Markdown 代码块
    if text.startswith("```"):
        text = text.strip("`")
        if text.startswith("json"):
            text = text[4:]
        text = text.strip()
    # 直接解析
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass
    # 正则提取第一个 {...}
    match = re.search(r'\{.*\}', text, re.DOTALL)
    if match:
        try:
            return json.loads(match.group(0))
        except json.JSONDecodeError:
            pass
    # 替换单引号尝试
    try:
        cleaned = text.replace("'", '"')
        return json.loads(cleaned)
    except json.JSONDecodeError:
        return None

定义翻译函数，包含重试：

def translate(user_input: str, max_retries: int = 2) -> dict:
    """翻译用户输入，返回解析后的字典，包含 detected_language, target_language, translation"""
    system_prompt = (
        "你是一个专业的翻译助手。你会收到用户输入的一段文本，请自动判断其语言（中文或英文）。"
        "如果输入是中文，请将其翻译成英文；如果输入是英文，请将其翻译成中文。"
        "如果输入包含其他语言或无法识别，请在 translation 字段中返回错误提示。"
        "你必须只输出一个 JSON 对象，格式如下："
        '{"detected_language": "zh" 或 "en", "target_language": "en" 或 "zh", "translation": "翻译后的文本"}'
        "不要输出任何其他文字。"
    )
    user_prompt = f"请翻译以下文本：\n{user_input}"

    for attempt in range(max_retries + 1):
        try:
            response = client.chat.completions.create(
                model="deepseek-chat",
                messages=[
                    {"role": "system", "content": system_prompt},
                    {"role": "user", "content": user_prompt}
                ],
                temperature=0.1,  # 低温度保证格式稳定
                max_tokens=500
            )
            raw_output = response.choices[0].message.content
            parsed = extract_json(raw_output)
            if parsed and "translation" in parsed:
                return parsed
            # 如果解析失败或缺少字段，记录并重试
            print(f"[警告] 第{attempt+1}次尝试解析失败，原始输出：{raw_output[:100]}...")
        except Exception as e:
            print(f"[错误] API调用异常：{e}")
        time.sleep(1)  # 简单等待
    # 所有重试失败
    return {"detected_language": "unknown", "target_language": "unknown", "translation": "翻译失败，请稍后重试。"}

步骤 4：构建命令行交互循环

def main():
    print("欢迎使用中英互译命令行工具！")
    print("输入中文自动翻译成英文，输入英文自动翻译成中文。")
    print("输入 '退出' 或 'quit' 结束程序。\n")
    while True:
        user_input = input("请输入：").strip()
        if not user_input:
            continue
        if user_input.lower() in ["退出", "quit", "exit"]:
            print("感谢使用，再见！")
            break
        result = translate(user_input)
        # 展示结果
        print("-" * 40)
        print(f"检测语言：{result.get('detected_language')}")
        print(f"目标语言：{result.get('target_language')}")
        print(f"翻译结果：{result.get('translation')}")
        print("-" * 40)

运行入口：

if __name__ == "__main__":
    main()

步骤 5：测试与调试

保存文件并运行：

python translator.py

测试用例：

输入“你好，世界” → 期望输出英文翻译。
输入“Hello, how are you?” → 期望输出中文翻译。
输入“12345” 或纯符号 → 可能返回错误提示（但模型可能仍会输出某种结果，注意观察）。
输入混合语言“你好world” → 观察模型如何处理。

观察点：

模型是否稳定输出 JSON？
解析成功率如何？
重试机制是否触发？
翻译质量是否满意？

如果发现 JSON 解析失败频繁，可以调整 Prompt（比如增加“严格禁止任何额外的文字”）或者优化 extract_json 函数。如果翻译质量不佳，可以考虑在 System Prompt 中加入 Few-shot 示例（例如在 System Prompt 中添加一个示例，展示输入“你好”时输出 {"detected_language":"zh","target_language":"en","translation":"Hello"}）。

步骤 6：代码整理与版本管理（可选）

将代码拆分为多个文件：llm_client.py（客户端初始化）、utils.py（JSON 提取）、translator.py（主逻辑）。
添加 requirements.txt 文件，记录依赖。
初始化 Git 仓库，提交代码，并创建 .gitignore 忽略 .env 和 __pycache__。
在 GitHub 上创建仓库，推送代码。

三、常见问题与调试

Q1：模型总是返回额外的解释文字，导致 JSON 解析失败。
→ 在 System Prompt 中加强语气，例如：“你只能输出 JSON 对象，绝对禁止输出任何其他文字，包括解释、提示、代码块标记。不要使用 Markdown。” 同时降低 temperature 至 0。

Q2：输入长文本时翻译被截断。
→ 检查 max_tokens 设置，翻译通常不需要太长，但若输入较长，可适当增大 max_tokens（例如 1000）。同时确保不超过模型的上下文窗口（DeepSeek 为 64K，一般不会超）。

Q3：有时模型检测语言错误（比如把中文拼音判断成英文）。
→ 可以在 Prompt 中加入更明确的判断规则，例如：“如果输入包含中文字符，则判定为中文；否则判定为英文。” 或者干脆不依赖模型判断，用代码检测（如 if any('\u4e00' <= ch <= '\u9fff' for ch in text)），然后明确告诉模型翻译方向。这样可以提高稳定性和速度。我们今天的实现让模型判断是为了练习 Prompt 设计，实际项目中你可能更倾向于代码判断。

Q4：重试机制是否必要？如果一直失败怎么办？
→ 重试是必要的，因为模型有随机性。如果连续失败，可以返回友好错误信息，让用户稍后再试。实际项目中还可加入指数退避等待。

Q5：如何改进翻译质量？
→ 可以加入 Few-shot 示例，或者使用专门的翻译 Prompt 技巧，比如要求“忠实原文，保持风格”。如果有领域要求，可在 System Prompt 中说明。

四、今日总结与作业

今天你完成了：

✅ 构建了一个可用的命令行翻译软件，整合了 API 调用、Prompt 设计、JSON 解析、重试机制。
✅ 通过实战巩固了对结构化输出的理解，并学习了如何让程序稳定地与模型协作。
✅ 体验了从零到一搭建一个小型 LLM 应用的过程。

今日作业（必做）：

运行你的翻译软件，测试 10 个不同的句子（5 个中文、5 个英文），记录翻译质量和解析成功率。
尝试优化 Prompt 或代码，提高 JSON 解析成功率（比如加入 Few-shot 示例，或改用代码判断语言）。记录优化前后的对比。
将今天和本周的代码整理到一个 GitHub 仓库中，确保 README 描述清楚项目结构和运行方法。这是你 AI 学习之旅的第一个里程碑！

明日预告： 我们将进入第二周，深入学习提示词工程的进阶技巧：如何防范模型幻觉、角色扮演、长文本摘要等。请保持好奇心和耐心，我们继续前进！

有任何问题欢迎随时提问！

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/jjj_web/article/details/165118183

【三个月 AI Agent 实战学习】Day 7 ：阶段总结 —— 命令行翻译软件实战