1. 背景与核心概念最近在探索如何将前沿的AI能力与游戏体验相结合DeepSeek作为一款强大的大语言模型其API的开放性和灵活性为开发者提供了广阔的想象空间。而《光·遇》这款游戏以其唯美的画面和治愈的社交体验著称玩家在游戏中通过收集“光之翼”、解锁动作、结交朋友来体验旅程。一个自然的想法是能否让DeepSeek的智能对话能力“接入”《光·遇》为玩家创造更丰富的互动体验比如让AI扮演游戏中的向导、故事讲述者或者帮助玩家解答游戏内的谜题和机制。本文所指的“DeepSeek接入光遇效果展示”并非指通过技术手段直接修改游戏客户端或服务器来实现深度集成这通常违反游戏用户协议而是探讨一种在游戏外部利用DeepSeek API构建一个辅助工具或互动伴侣的方案。这种方案的核心思路是玩家在游戏过程中遇到问题或想分享见闻时可以切换到我们开发的工具中与基于DeepSeek构建的AI角色进行对话获得游戏攻略、背景故事解读或纯粹的陪伴式聊天。这种“接入”的本质是创建一个与《光·遇》主题和世界观深度绑定的AI聊天应用。它解决了玩家在独自探索时缺乏即时指引、渴望了解更多游戏文化背景或单纯希望有个“伙伴”聊聊游戏见闻的需求。对于开发者而言这是一个学习如何调用大模型API、设计提示词Prompt Engineering以及构建完整应用链路的绝佳实战项目。2. 环境准备与版本说明在开始构建我们的“光遇AI助手”之前需要准备好开发环境。本项目是一个全栈应用示例前端负责用户交互后端处理逻辑并调用DeepSeek API。操作系统: Windows 10/11, macOS 或 Linux 均可。本文示例在 macOS 环境下开发。后端技术栈:编程语言: Python 3.9Web框架: FastAPI (轻量级异步支持好)HTTP客户端:httpx或aiohttp(用于异步调用DeepSeek API)环境管理:pip和venv(用于创建虚拟环境)前端技术栈(可选用于展示效果):简单的HTML/JavaScript页面或使用Streamlit快速构建界面。本文为简化流程后端将直接返回JSON可使用Postman或curl测试。同时会提供一个极简的Streamlit前端示例。DeepSeek API:你需要一个DeepSeek API Key。请访问DeepSeek官方平台注册并获取。本文撰写时DeepSeek API的模型版本为deepseek-chat基础URL为https://api.deepseek.com。请注意API的URL、模型名称和计费策略可能更新请以官方最新文档为准。项目结构预览:sky-ai-assistant/ ├── backend/ │ ├── main.py # FastAPI 主应用文件 │ ├── requirements.txt # Python依赖列表 │ └── .env # 环境变量文件存储API Key ├── frontend/ # 可选前端文件 │ └── app.py # Streamlit 应用文件 └── README.md3. 核心原理与API调用拆解整个项目的核心在于后端服务如何与DeepSeek API进行通信。我们将其拆解为几个关键部分认证、请求构造、响应处理以及提示词设计。3.1 DeepSeek API 认证与请求格式DeepSeek API 通常采用Bearer Token的方式进行认证。你需要将获取到的API Key放在HTTP请求头的Authorization字段中。一个标准的Chat Completion请求格式如下以OpenAI兼容格式为例DeepSeek API通常与此类似请求体关键参数:model: 指定使用的模型如deepseek-chat。messages: 一个消息对象数组定义了对话的历史和当前提问。每个消息对象包含role和content。role: 可以是system系统指令、user用户输入、assistantAI回复。max_tokens: 控制AI回复的最大长度。temperature: 控制回复的随机性0.0更确定1.0更随机。3.2 提示词Prompt工程为《光·遇》定制AI角色这是本项目最具创意和技术含量的部分。直接让DeepSeek回答《光·遇》问题可能效果不佳我们需要通过system角色消息来塑造一个专业的“光之向导”。一个基础的系统提示词示例你是一位资深的《光·遇》游戏向导名叫“星引”。你熟悉游戏中的所有地图晨岛、云野、雨林、霞谷、暮土、禁阁、伊甸、先祖故事、光之翼位置、季节任务和社交礼仪。你的语气温暖、耐心、充满鼓励就像游戏中的老玩家一样。你会用游戏内的术语如“小金人”、“献祭”、“复刻先祖”进行回答。如果用户询问游戏外或无关内容你会礼貌地将对话引导回《光·遇》的世界。这个提示词定义了AI的角色、知识范围和语气能显著提升对话的相关性和沉浸感。3.3 异步调用与错误处理在Web后端中调用外部API是I/O密集型操作使用异步请求可以避免阻塞服务器线程提高并发能力。我们需要使用像httpx.AsyncClient这样的异步客户端。同时必须做好错误处理包括网络超时、API额度不足、响应格式异常等。4. 完整实战案例构建光遇AI助手后端接下来我们从零开始搭建后端服务。4.1 创建项目结构与虚拟环境首先创建项目目录并初始化Python虚拟环境。# 创建项目目录 mkdir sky-ai-assistant cd sky-ai-assistant mkdir backend frontend # 进入后端目录并创建虚拟环境 cd backend python3 -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 安装核心依赖 pip install fastapi uvicorn httpx python-dotenv4.2 配置环境变量与项目依赖在backend目录下创建.env文件用于安全地存储API Key。切记不要将此文件提交到Git等版本控制系统。# backend/.env DEEPSEEK_API_KEYyour_deepseek_api_key_here DEEPSEEK_API_BASEhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat然后创建requirements.txt文件记录项目依赖。# backend/requirements.txt fastapi0.104.1 uvicorn[standard]0.24.0 httpx0.25.1 python-dotenv1.0.04.3 编写核心后端代码创建backend/main.py文件这是我们的FastAPI应用主文件。# backend/main.py import os from typing import List, Optional from fastapi import FastAPI, HTTPException from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel import httpx from dotenv import load_dotenv import asyncio # 加载环境变量 load_dotenv() # 从环境变量读取配置 DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY) DEEPSEEK_API_BASE os.getenv(DEEPSEEK_API_BASE, https://api.deepseek.com) DEEPSEEK_MODEL os.getenv(DEEPSEEK_MODEL, deepseek-chat) # 验证配置 if not DEEPSEEK_API_KEY: raise ValueError(请在 .env 文件中设置 DEEPSEEK_API_KEY) # 初始化FastAPI应用 app FastAPI(title光遇AI助手API, description基于DeepSeek API的《光·遇》游戏助手) # 配置CORS允许前端跨域访问如果前端独立部署 app.add_middleware( CORSMiddleware, allow_origins[*], # 生产环境应替换为具体的前端域名 allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 定义请求和响应的数据模型 class ChatMessage(BaseModel): role: str # user, assistant, system content: str class ChatRequest(BaseModel): messages: List[ChatMessage] max_tokens: Optional[int] 1024 temperature: Optional[float] 0.7 class ChatResponse(BaseModel): reply: str model_used: str # 核心与DeepSeek API通信的异步函数 async def call_deepseek_api(messages: List[dict], max_tokens: int, temperature: float) - str: 调用DeepSeek Chat Completion API。 url f{DEEPSEEK_API_BASE}/chat/completions headers { Authorization: fBearer {DEEPSEEK_API_KEY}, Content-Type: application/json, } payload { model: DEEPSEEK_MODEL, messages: messages, max_tokens: max_tokens, temperature: temperature, stream: False # 非流式响应 } # 设置超时避免长时间等待 timeout httpx.Timeout(30.0, connect10.0) async with httpx.AsyncClient(timeouttimeout) as client: try: response await client.post(url, jsonpayload, headersheaders) response.raise_for_status() # 如果状态码不是2xx抛出异常 result response.json() # 提取AI回复内容 reply result[choices][0][message][content] return reply.strip() except httpx.HTTPStatusError as e: raise HTTPException( status_codee.response.status_code, detailfDeepSeek API 错误: {e.response.text} ) except httpx.RequestError as e: raise HTTPException( status_code500, detailf网络请求失败: {str(e)} ) except (KeyError, IndexError) as e: raise HTTPException( status_code500, detailf解析DeepSeek API响应失败: {str(e)} ) # 定义光遇向导的系统提示词 SKY_GUIDE_SYSTEM_PROMPT 你是一位资深的《光·遇》游戏向导名叫“星引”。你熟悉游戏中的所有地图晨岛、云野、雨林、霞谷、暮土、禁阁、伊甸、先祖故事、光之翼位置、季节任务和社交礼仪。你的语气温暖、耐心、充满鼓励就像游戏中的老玩家一样。你会用游戏内的术语如“小金人”、“献祭”、“复刻先祖”进行回答。如果用户询问游戏外或无关内容你会礼貌地将对话引导回《光·遇》的世界。你的回答应简洁、准确、富有帮助性。 # 核心聊天端点 app.post(/chat, response_modelChatResponse) async def chat_with_sky_guide(request: ChatRequest): 与光遇AI助手对话。 客户端发送对话历史服务端会附加系统提示词后调用DeepSeek API。 # 1. 构建完整的消息列表系统提示词 历史对话 full_messages [{role: system, content: SKY_GUIDE_SYSTEM_PROMPT}] # 将Pydantic模型列表转换为字典列表 for msg in request.messages: full_messages.append({role: msg.role, content: msg.content}) # 2. 调用DeepSeek API try: ai_reply await call_deepseek_api( messagesfull_messages, max_tokensrequest.max_tokens, temperaturerequest.temperature ) except HTTPException as e: # 直接抛出FastAPI的HTTP异常 raise e except Exception as e: # 捕获其他未预料异常 raise HTTPException(status_code500, detailf内部服务器错误: {str(e)}) # 3. 返回响应 return ChatResponse(replyai_reply, model_usedDEEPSEEK_MODEL) # 健康检查端点 app.get(/health) async def health_check(): return {status: healthy, service: sky-ai-assistant-backend} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)4.4 运行与验证后端服务保存代码后在backend目录下启动服务。# 确保虚拟环境已激活并在 backend/ 目录下 python main.py # 或使用 uvicorn 命令指定重载开发模式 # uvicorn main:app --reload --host 0.0.0.0 --port 8000服务启动后默认运行在http://localhost:8000。你可以通过以下方式测试1. 使用浏览器访问健康检查接口打开浏览器访问http://localhost:8000/health应该看到{status: healthy, ...}的JSON响应。2. 使用curl命令测试聊天接口curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d { messages: [ {role: user, content: 雨林地图的光之翼都在哪里我老是漏掉几个。} ], max_tokens: 500, temperature: 0.7 }3. 使用Python脚本测试# test_api.py import asyncio import httpx import json async def test_chat(): async with httpx.AsyncClient() as client: payload { messages: [{role: user, content: 第一次去伊甸要注意什么}], max_tokens: 600 } response await client.post(http://localhost:8000/chat, jsonpayload) print(f状态码: {response.status_code}) print(f响应内容: {response.json()}) if __name__ __main__: asyncio.run(test_chat())4.5 可选构建一个极简Streamlit前端为了更直观地展示“接入效果”我们可以快速构建一个Web界面。在frontend目录下创建app.py。# frontend/app.py import streamlit as st import requests import json # 页面配置 st.set_page_config(page_title光遇AI助手 - 星引, page_icon✨) st.title(✨ 光遇AI助手 - 星引) st.markdown(你好旅人我是你的光之向导 **星引**。关于晨岛、云野、雨林...的任何问题我都可以为你解答。) # 初始化会话状态保存对话历史 if messages not in st.session_state: st.session_state.messages [] # 添加一条初始欢迎消息可选由AI生成更好 st.session_state.messages.append({role: assistant, content: 你好旅人我是星引一位光之向导。今天在天空王国探索时有什么需要帮助的吗}) # 显示历史对话 for message in st.session_state.messages: with st.chat_message(message[role]): st.markdown(message[content]) # 聊天输入框 if prompt : st.chat_input(输入你的问题例如雨林的小金人在哪): # 添加用户消息到历史并显示 st.session_state.messages.append({role: user, content: prompt}) with st.chat_message(user): st.markdown(prompt) # 准备调用后端API with st.chat_message(assistant): message_placeholder st.empty() # 占位符用于流式效果简化版先显示加载中 message_placeholder.markdown(⏳ 星引正在思考...) # 构建请求数据 api_url http://localhost:8000/chat # 后端服务地址 request_data { messages: st.session_state.messages[:-1], # 发送历史消息不包括刚添加的user消息 max_tokens: 1024, temperature: 0.7 } try: # 发送请求到后端 response requests.post(api_url, jsonrequest_data, timeout30) response.raise_for_status() result response.json() ai_reply result[reply] # 更新占位符为AI回复 message_placeholder.markdown(ai_reply) # 将AI回复添加到历史 st.session_state.messages.append({role: assistant, content: ai_reply}) except requests.exceptions.RequestException as e: message_placeholder.markdown(f❌ 抱歉连接向导失败了...请检查后端服务是否运行。错误信息{e}) # 侧边栏添加重置对话按钮 with st.sidebar: st.header(设置) if st.button(重置对话): st.session_state.messages [ {role: assistant, content: 对话已重置。你好旅人我是星引一位光之向导。今天在天空王国探索时有什么需要帮助的吗} ] st.rerun() st.markdown(---) st.markdown(**关于**) st.markdown(本助手基于DeepSeek大模型驱动专为《光·遇》玩家打造。) st.markdown(后端API服务运行在 localhost:8000)运行前端应用# 在项目根目录或 frontend/ 目录下 pip install streamlit requests streamlit run frontend/app.py访问http://localhost:8501即可与你的“光遇AI助手”对话了。5. 常见问题与排查思路在开发和运行过程中你可能会遇到以下问题问题现象常见原因解决思路启动后端服务时报错ModuleNotFoundErrorPython依赖未安装或虚拟环境未激活。1. 确认在backend/目录下。2. 执行pip install -r requirements.txt。3. 确认虚拟环境已激活命令行前缀有(venv)。访问http://localhost:8000/chat返回422 Unprocessable Entity请求体的JSON格式不符合ChatRequest模型定义。1. 检查messages字段是否为列表。2. 检查列表中每个对象是否有role和content字段。3. 使用Postman或curl时确保Content-Type: application/json头已设置。调用聊天接口返回401 Unauthorized或403 ForbiddenDeepSeek API Key 错误、过期或未设置。1. 检查backend/.env文件中的DEEPSEEK_API_KEY是否正确。2. 确认API Key有足够的余额或调用权限。3. 重启后端服务以使环境变量生效。后端服务报错Timeout或长时间无响应DeepSeek API 服务不稳定或网络连接问题。1. 检查网络连接。2. 在call_deepseek_api函数中增加timeout参数并设置合理的值如30秒。3. 添加重试机制需谨慎避免短时间内重复请求。AI回复内容与《光·遇》无关或质量差系统提示词 (SKY_GUIDE_SYSTEM_PROMPT) 不够精确或约束力不强。1. 优化系统提示词更详细地定义角色、知识边界和语气。2. 在提示词中明确要求“如果不知道请诚实回答不要编造”。3. 可以尝试在对话历史中由用户先设定场景例如“我们现在在云野聊天”。Streamlit前端无法连接到后端后端服务未启动或端口被占用或CORS配置问题。1. 确认后端服务正在运行 (http://localhost:8000/health可访问)。2. 检查frontend/app.py中的api_url是否正确。3. 后端CORS配置允许了前端来源开发环境可暂时设为allow_origins[*]。API调用返回内容包含奇怪格式或代码模型在生成时可能包含了Markdown或代码块。1. 这是模型行为可以在后处理阶段过滤掉特定标记。2. 或在系统提示词中增加要求“请用纯文本回复不要使用Markdown格式或代码块。”6. 最佳实践与工程建议将AI能力“接入”到具体场景时除了基础功能还需要考虑工程化、体验和成本。1. 提示词优化与迭代分场景细化可以为不同功能设计不同的系统提示词。例如“攻略查询模式”、“故事讲述模式”、“社交技巧模式”通过用户选择或关键词触发切换。上下文管理对话历史会消耗Token。需要设计策略在保持对话连贯性和控制成本之间平衡。例如只保留最近10轮对话或定期总结历史。防止Prompt注入对用户输入进行简单的过滤或检查防止用户输入恶意指令覆盖你的系统提示词。2. 后端服务增强配置管理使用pydantic-settings等库管理配置区分开发、测试、生产环境。日志记录集成loguru或structlog记录API请求、响应和错误便于排查问题。速率限制使用slowapi等中间件对/chat接口进行限流防止滥用。异步优化使用httpx.AsyncClient的会话复用并为可能长时间运行的请求设置合理的超时和取消机制。错误友好化将DeepSeek API返回的原始错误信息转换为对前端用户更友好的提示。3. 前端体验提升流式输出修改后端API支持Server-Sent Events (SSE) 或WebSocket实现AI回复的逐字输出效果提升体验。对话持久化将对话历史存储到数据库如SQLite、Redis或浏览器本地存储实现页面刷新后对话不丢失。预设问题提供一些常见问题按钮如“晨岛先祖位置”、“雨林躲雨技巧”方便用户快速提问。4. 安全与成本控制API Key保护后端服务必须将API Key存储在环境变量或安全的配置中心绝对不要硬编码在代码或前端。输入输出审核对用户输入和AI输出进行必要的审核过滤避免产生不当内容。Token计数与预算估算每次对话的Token消耗为免费用户或不同套餐设置每日调用上限防止意外成本。缓存策略对常见、静态的游戏攻略类问题如“云野有多少个小金人”可以将AI的回答缓存起来相同问题直接返回缓存结果大幅降低API调用成本和延迟。5. 关于《光·遇》游戏本身尊重版权与规则本项目是第三方辅助工具必须明确声明与游戏官方无关。所有游戏内容版权归属Thatgamecompany。倡导健康游戏AI助手的内容应引导玩家享受游戏、探索和社交而不是鼓励过度肝或利用漏洞。数据时效性游戏版本更新新季节、新地图后AI的知识可能过时。需要建立机制定期用最新的官方信息更新系统提示词或知识库。通过以上步骤你不仅完成了一个“DeepSeek接入光遇”的效果展示更实践了一个完整的AI应用后端开发流程。从环境搭建、API调用、提示词设计到服务部署和优化这套方法论可以迁移到任何你想用大语言模型增强的垂直场景中。 基于DeepSeek API构建光遇AI助手：从提示词工程到全栈实践
1. 背景与核心概念最近在探索如何将前沿的AI能力与游戏体验相结合DeepSeek作为一款强大的大语言模型其API的开放性和灵活性为开发者提供了广阔的想象空间。而《光·遇》这款游戏以其唯美的画面和治愈的社交体验著称玩家在游戏中通过收集“光之翼”、解锁动作、结交朋友来体验旅程。一个自然的想法是能否让DeepSeek的智能对话能力“接入”《光·遇》为玩家创造更丰富的互动体验比如让AI扮演游戏中的向导、故事讲述者或者帮助玩家解答游戏内的谜题和机制。本文所指的“DeepSeek接入光遇效果展示”并非指通过技术手段直接修改游戏客户端或服务器来实现深度集成这通常违反游戏用户协议而是探讨一种在游戏外部利用DeepSeek API构建一个辅助工具或互动伴侣的方案。这种方案的核心思路是玩家在游戏过程中遇到问题或想分享见闻时可以切换到我们开发的工具中与基于DeepSeek构建的AI角色进行对话获得游戏攻略、背景故事解读或纯粹的陪伴式聊天。这种“接入”的本质是创建一个与《光·遇》主题和世界观深度绑定的AI聊天应用。它解决了玩家在独自探索时缺乏即时指引、渴望了解更多游戏文化背景或单纯希望有个“伙伴”聊聊游戏见闻的需求。对于开发者而言这是一个学习如何调用大模型API、设计提示词Prompt Engineering以及构建完整应用链路的绝佳实战项目。2. 环境准备与版本说明在开始构建我们的“光遇AI助手”之前需要准备好开发环境。本项目是一个全栈应用示例前端负责用户交互后端处理逻辑并调用DeepSeek API。操作系统: Windows 10/11, macOS 或 Linux 均可。本文示例在 macOS 环境下开发。后端技术栈:编程语言: Python 3.9Web框架: FastAPI (轻量级异步支持好)HTTP客户端:httpx或aiohttp(用于异步调用DeepSeek API)环境管理:pip和venv(用于创建虚拟环境)前端技术栈(可选用于展示效果):简单的HTML/JavaScript页面或使用Streamlit快速构建界面。本文为简化流程后端将直接返回JSON可使用Postman或curl测试。同时会提供一个极简的Streamlit前端示例。DeepSeek API:你需要一个DeepSeek API Key。请访问DeepSeek官方平台注册并获取。本文撰写时DeepSeek API的模型版本为deepseek-chat基础URL为https://api.deepseek.com。请注意API的URL、模型名称和计费策略可能更新请以官方最新文档为准。项目结构预览:sky-ai-assistant/ ├── backend/ │ ├── main.py # FastAPI 主应用文件 │ ├── requirements.txt # Python依赖列表 │ └── .env # 环境变量文件存储API Key ├── frontend/ # 可选前端文件 │ └── app.py # Streamlit 应用文件 └── README.md3. 核心原理与API调用拆解整个项目的核心在于后端服务如何与DeepSeek API进行通信。我们将其拆解为几个关键部分认证、请求构造、响应处理以及提示词设计。3.1 DeepSeek API 认证与请求格式DeepSeek API 通常采用Bearer Token的方式进行认证。你需要将获取到的API Key放在HTTP请求头的Authorization字段中。一个标准的Chat Completion请求格式如下以OpenAI兼容格式为例DeepSeek API通常与此类似请求体关键参数:model: 指定使用的模型如deepseek-chat。messages: 一个消息对象数组定义了对话的历史和当前提问。每个消息对象包含role和content。role: 可以是system系统指令、user用户输入、assistantAI回复。max_tokens: 控制AI回复的最大长度。temperature: 控制回复的随机性0.0更确定1.0更随机。3.2 提示词Prompt工程为《光·遇》定制AI角色这是本项目最具创意和技术含量的部分。直接让DeepSeek回答《光·遇》问题可能效果不佳我们需要通过system角色消息来塑造一个专业的“光之向导”。一个基础的系统提示词示例你是一位资深的《光·遇》游戏向导名叫“星引”。你熟悉游戏中的所有地图晨岛、云野、雨林、霞谷、暮土、禁阁、伊甸、先祖故事、光之翼位置、季节任务和社交礼仪。你的语气温暖、耐心、充满鼓励就像游戏中的老玩家一样。你会用游戏内的术语如“小金人”、“献祭”、“复刻先祖”进行回答。如果用户询问游戏外或无关内容你会礼貌地将对话引导回《光·遇》的世界。这个提示词定义了AI的角色、知识范围和语气能显著提升对话的相关性和沉浸感。3.3 异步调用与错误处理在Web后端中调用外部API是I/O密集型操作使用异步请求可以避免阻塞服务器线程提高并发能力。我们需要使用像httpx.AsyncClient这样的异步客户端。同时必须做好错误处理包括网络超时、API额度不足、响应格式异常等。4. 完整实战案例构建光遇AI助手后端接下来我们从零开始搭建后端服务。4.1 创建项目结构与虚拟环境首先创建项目目录并初始化Python虚拟环境。# 创建项目目录 mkdir sky-ai-assistant cd sky-ai-assistant mkdir backend frontend # 进入后端目录并创建虚拟环境 cd backend python3 -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 安装核心依赖 pip install fastapi uvicorn httpx python-dotenv4.2 配置环境变量与项目依赖在backend目录下创建.env文件用于安全地存储API Key。切记不要将此文件提交到Git等版本控制系统。# backend/.env DEEPSEEK_API_KEYyour_deepseek_api_key_here DEEPSEEK_API_BASEhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat然后创建requirements.txt文件记录项目依赖。# backend/requirements.txt fastapi0.104.1 uvicorn[standard]0.24.0 httpx0.25.1 python-dotenv1.0.04.3 编写核心后端代码创建backend/main.py文件这是我们的FastAPI应用主文件。# backend/main.py import os from typing import List, Optional from fastapi import FastAPI, HTTPException from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel import httpx from dotenv import load_dotenv import asyncio # 加载环境变量 load_dotenv() # 从环境变量读取配置 DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY) DEEPSEEK_API_BASE os.getenv(DEEPSEEK_API_BASE, https://api.deepseek.com) DEEPSEEK_MODEL os.getenv(DEEPSEEK_MODEL, deepseek-chat) # 验证配置 if not DEEPSEEK_API_KEY: raise ValueError(请在 .env 文件中设置 DEEPSEEK_API_KEY) # 初始化FastAPI应用 app FastAPI(title光遇AI助手API, description基于DeepSeek API的《光·遇》游戏助手) # 配置CORS允许前端跨域访问如果前端独立部署 app.add_middleware( CORSMiddleware, allow_origins[*], # 生产环境应替换为具体的前端域名 allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 定义请求和响应的数据模型 class ChatMessage(BaseModel): role: str # user, assistant, system content: str class ChatRequest(BaseModel): messages: List[ChatMessage] max_tokens: Optional[int] 1024 temperature: Optional[float] 0.7 class ChatResponse(BaseModel): reply: str model_used: str # 核心与DeepSeek API通信的异步函数 async def call_deepseek_api(messages: List[dict], max_tokens: int, temperature: float) - str: 调用DeepSeek Chat Completion API。 url f{DEEPSEEK_API_BASE}/chat/completions headers { Authorization: fBearer {DEEPSEEK_API_KEY}, Content-Type: application/json, } payload { model: DEEPSEEK_MODEL, messages: messages, max_tokens: max_tokens, temperature: temperature, stream: False # 非流式响应 } # 设置超时避免长时间等待 timeout httpx.Timeout(30.0, connect10.0) async with httpx.AsyncClient(timeouttimeout) as client: try: response await client.post(url, jsonpayload, headersheaders) response.raise_for_status() # 如果状态码不是2xx抛出异常 result response.json() # 提取AI回复内容 reply result[choices][0][message][content] return reply.strip() except httpx.HTTPStatusError as e: raise HTTPException( status_codee.response.status_code, detailfDeepSeek API 错误: {e.response.text} ) except httpx.RequestError as e: raise HTTPException( status_code500, detailf网络请求失败: {str(e)} ) except (KeyError, IndexError) as e: raise HTTPException( status_code500, detailf解析DeepSeek API响应失败: {str(e)} ) # 定义光遇向导的系统提示词 SKY_GUIDE_SYSTEM_PROMPT 你是一位资深的《光·遇》游戏向导名叫“星引”。你熟悉游戏中的所有地图晨岛、云野、雨林、霞谷、暮土、禁阁、伊甸、先祖故事、光之翼位置、季节任务和社交礼仪。你的语气温暖、耐心、充满鼓励就像游戏中的老玩家一样。你会用游戏内的术语如“小金人”、“献祭”、“复刻先祖”进行回答。如果用户询问游戏外或无关内容你会礼貌地将对话引导回《光·遇》的世界。你的回答应简洁、准确、富有帮助性。 # 核心聊天端点 app.post(/chat, response_modelChatResponse) async def chat_with_sky_guide(request: ChatRequest): 与光遇AI助手对话。 客户端发送对话历史服务端会附加系统提示词后调用DeepSeek API。 # 1. 构建完整的消息列表系统提示词 历史对话 full_messages [{role: system, content: SKY_GUIDE_SYSTEM_PROMPT}] # 将Pydantic模型列表转换为字典列表 for msg in request.messages: full_messages.append({role: msg.role, content: msg.content}) # 2. 调用DeepSeek API try: ai_reply await call_deepseek_api( messagesfull_messages, max_tokensrequest.max_tokens, temperaturerequest.temperature ) except HTTPException as e: # 直接抛出FastAPI的HTTP异常 raise e except Exception as e: # 捕获其他未预料异常 raise HTTPException(status_code500, detailf内部服务器错误: {str(e)}) # 3. 返回响应 return ChatResponse(replyai_reply, model_usedDEEPSEEK_MODEL) # 健康检查端点 app.get(/health) async def health_check(): return {status: healthy, service: sky-ai-assistant-backend} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)4.4 运行与验证后端服务保存代码后在backend目录下启动服务。# 确保虚拟环境已激活并在 backend/ 目录下 python main.py # 或使用 uvicorn 命令指定重载开发模式 # uvicorn main:app --reload --host 0.0.0.0 --port 8000服务启动后默认运行在http://localhost:8000。你可以通过以下方式测试1. 使用浏览器访问健康检查接口打开浏览器访问http://localhost:8000/health应该看到{status: healthy, ...}的JSON响应。2. 使用curl命令测试聊天接口curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d { messages: [ {role: user, content: 雨林地图的光之翼都在哪里我老是漏掉几个。} ], max_tokens: 500, temperature: 0.7 }3. 使用Python脚本测试# test_api.py import asyncio import httpx import json async def test_chat(): async with httpx.AsyncClient() as client: payload { messages: [{role: user, content: 第一次去伊甸要注意什么}], max_tokens: 600 } response await client.post(http://localhost:8000/chat, jsonpayload) print(f状态码: {response.status_code}) print(f响应内容: {response.json()}) if __name__ __main__: asyncio.run(test_chat())4.5 可选构建一个极简Streamlit前端为了更直观地展示“接入效果”我们可以快速构建一个Web界面。在frontend目录下创建app.py。# frontend/app.py import streamlit as st import requests import json # 页面配置 st.set_page_config(page_title光遇AI助手 - 星引, page_icon✨) st.title(✨ 光遇AI助手 - 星引) st.markdown(你好旅人我是你的光之向导 **星引**。关于晨岛、云野、雨林...的任何问题我都可以为你解答。) # 初始化会话状态保存对话历史 if messages not in st.session_state: st.session_state.messages [] # 添加一条初始欢迎消息可选由AI生成更好 st.session_state.messages.append({role: assistant, content: 你好旅人我是星引一位光之向导。今天在天空王国探索时有什么需要帮助的吗}) # 显示历史对话 for message in st.session_state.messages: with st.chat_message(message[role]): st.markdown(message[content]) # 聊天输入框 if prompt : st.chat_input(输入你的问题例如雨林的小金人在哪): # 添加用户消息到历史并显示 st.session_state.messages.append({role: user, content: prompt}) with st.chat_message(user): st.markdown(prompt) # 准备调用后端API with st.chat_message(assistant): message_placeholder st.empty() # 占位符用于流式效果简化版先显示加载中 message_placeholder.markdown(⏳ 星引正在思考...) # 构建请求数据 api_url http://localhost:8000/chat # 后端服务地址 request_data { messages: st.session_state.messages[:-1], # 发送历史消息不包括刚添加的user消息 max_tokens: 1024, temperature: 0.7 } try: # 发送请求到后端 response requests.post(api_url, jsonrequest_data, timeout30) response.raise_for_status() result response.json() ai_reply result[reply] # 更新占位符为AI回复 message_placeholder.markdown(ai_reply) # 将AI回复添加到历史 st.session_state.messages.append({role: assistant, content: ai_reply}) except requests.exceptions.RequestException as e: message_placeholder.markdown(f❌ 抱歉连接向导失败了...请检查后端服务是否运行。错误信息{e}) # 侧边栏添加重置对话按钮 with st.sidebar: st.header(设置) if st.button(重置对话): st.session_state.messages [ {role: assistant, content: 对话已重置。你好旅人我是星引一位光之向导。今天在天空王国探索时有什么需要帮助的吗} ] st.rerun() st.markdown(---) st.markdown(**关于**) st.markdown(本助手基于DeepSeek大模型驱动专为《光·遇》玩家打造。) st.markdown(后端API服务运行在 localhost:8000)运行前端应用# 在项目根目录或 frontend/ 目录下 pip install streamlit requests streamlit run frontend/app.py访问http://localhost:8501即可与你的“光遇AI助手”对话了。5. 常见问题与排查思路在开发和运行过程中你可能会遇到以下问题问题现象常见原因解决思路启动后端服务时报错ModuleNotFoundErrorPython依赖未安装或虚拟环境未激活。1. 确认在backend/目录下。2. 执行pip install -r requirements.txt。3. 确认虚拟环境已激活命令行前缀有(venv)。访问http://localhost:8000/chat返回422 Unprocessable Entity请求体的JSON格式不符合ChatRequest模型定义。1. 检查messages字段是否为列表。2. 检查列表中每个对象是否有role和content字段。3. 使用Postman或curl时确保Content-Type: application/json头已设置。调用聊天接口返回401 Unauthorized或403 ForbiddenDeepSeek API Key 错误、过期或未设置。1. 检查backend/.env文件中的DEEPSEEK_API_KEY是否正确。2. 确认API Key有足够的余额或调用权限。3. 重启后端服务以使环境变量生效。后端服务报错Timeout或长时间无响应DeepSeek API 服务不稳定或网络连接问题。1. 检查网络连接。2. 在call_deepseek_api函数中增加timeout参数并设置合理的值如30秒。3. 添加重试机制需谨慎避免短时间内重复请求。AI回复内容与《光·遇》无关或质量差系统提示词 (SKY_GUIDE_SYSTEM_PROMPT) 不够精确或约束力不强。1. 优化系统提示词更详细地定义角色、知识边界和语气。2. 在提示词中明确要求“如果不知道请诚实回答不要编造”。3. 可以尝试在对话历史中由用户先设定场景例如“我们现在在云野聊天”。Streamlit前端无法连接到后端后端服务未启动或端口被占用或CORS配置问题。1. 确认后端服务正在运行 (http://localhost:8000/health可访问)。2. 检查frontend/app.py中的api_url是否正确。3. 后端CORS配置允许了前端来源开发环境可暂时设为allow_origins[*]。API调用返回内容包含奇怪格式或代码模型在生成时可能包含了Markdown或代码块。1. 这是模型行为可以在后处理阶段过滤掉特定标记。2. 或在系统提示词中增加要求“请用纯文本回复不要使用Markdown格式或代码块。”6. 最佳实践与工程建议将AI能力“接入”到具体场景时除了基础功能还需要考虑工程化、体验和成本。1. 提示词优化与迭代分场景细化可以为不同功能设计不同的系统提示词。例如“攻略查询模式”、“故事讲述模式”、“社交技巧模式”通过用户选择或关键词触发切换。上下文管理对话历史会消耗Token。需要设计策略在保持对话连贯性和控制成本之间平衡。例如只保留最近10轮对话或定期总结历史。防止Prompt注入对用户输入进行简单的过滤或检查防止用户输入恶意指令覆盖你的系统提示词。2. 后端服务增强配置管理使用pydantic-settings等库管理配置区分开发、测试、生产环境。日志记录集成loguru或structlog记录API请求、响应和错误便于排查问题。速率限制使用slowapi等中间件对/chat接口进行限流防止滥用。异步优化使用httpx.AsyncClient的会话复用并为可能长时间运行的请求设置合理的超时和取消机制。错误友好化将DeepSeek API返回的原始错误信息转换为对前端用户更友好的提示。3. 前端体验提升流式输出修改后端API支持Server-Sent Events (SSE) 或WebSocket实现AI回复的逐字输出效果提升体验。对话持久化将对话历史存储到数据库如SQLite、Redis或浏览器本地存储实现页面刷新后对话不丢失。预设问题提供一些常见问题按钮如“晨岛先祖位置”、“雨林躲雨技巧”方便用户快速提问。4. 安全与成本控制API Key保护后端服务必须将API Key存储在环境变量或安全的配置中心绝对不要硬编码在代码或前端。输入输出审核对用户输入和AI输出进行必要的审核过滤避免产生不当内容。Token计数与预算估算每次对话的Token消耗为免费用户或不同套餐设置每日调用上限防止意外成本。缓存策略对常见、静态的游戏攻略类问题如“云野有多少个小金人”可以将AI的回答缓存起来相同问题直接返回缓存结果大幅降低API调用成本和延迟。5. 关于《光·遇》游戏本身尊重版权与规则本项目是第三方辅助工具必须明确声明与游戏官方无关。所有游戏内容版权归属Thatgamecompany。倡导健康游戏AI助手的内容应引导玩家享受游戏、探索和社交而不是鼓励过度肝或利用漏洞。数据时效性游戏版本更新新季节、新地图后AI的知识可能过时。需要建立机制定期用最新的官方信息更新系统提示词或知识库。通过以上步骤你不仅完成了一个“DeepSeek接入光遇”的效果展示更实践了一个完整的AI应用后端开发流程。从环境搭建、API调用、提示词设计到服务部署和优化这套方法论可以迁移到任何你想用大语言模型增强的垂直场景中。