DEV Community: caofan99521

Understanding Deepseek API with the "House-Building"Analogy

caofan99521 — Tue, 24 Mar 2026 14:11:25 +0000

可以理解成“从0到住进一套‘AI智能小屋’”的盖房子流程，每一步都对应相应的知识和操作方法：

第一步：明确建房目标（认知层）

搞懂“为社么要学Deepseek API”

你要该的房子：一套能够通过代码自动调用AI 干活的“智能小屋”
两种户型
Chat 户型：日常聊天、写文案、答问题（小户型，简单好住）
R1推理户型：解数学题、做逻辑分析、写复杂方案（大户型，功能更强）
核心认知：API 就是“用代码开门喊AI 干活”，不用懂AI内部怎么造，只要会用就行

第二步：备齐建房材料（准备层）

对应知识：准备调用API的基础条件

买地+领钥匙：

去Deepseek 官方网站注册账号，申请API Key （这是进入AI 大门的唯一钥匙，丢了就进不去）
把Key存好，别泄漏（就像家门钥匙不能随便给人）

备工具+建材：

安装python（这是盖房子的‘施工队’）
用uv快速搭建虚拟环境（相当于给施工队画好施工区域，避免乱堆材料）
安装依赖库：

requests：搬砖工具，负责给AI 发请求、搬回答案案

openai：电动工具包，后面简化调用

逻辑：没钥匙进不了门，没工具盖不了房，这一步是所有操作的前提

第三步：打牢地基（原理层）

理解API 请求-相应的底层逻辑

地基结构：“你发请求→AI处理→AI会响应”

请求（你给AI 的指令）：

带钥匙（API Key）：证明你是合法住户

说清用哪套户型（model：deepseek-chat或deepseek-reasoner）

说清楚要做什么（messages：你的问题/需求）

响应（AI给你的结果）：

返回JSON 格式的“装修图纸”

真正的答案藏在choices[0].message.content 里（就像图纸里的核心施工说明）

实操方法：用requests 库手写一次原生请求，就像亲手挖地基、绑钢筋，彻底搞懂“请求-响应”的本质

第四步：砌起第一面墙（基础实操层）

调用Chat聊天模型

砌墙目标：先改好小户型（Chat模型），确保能正常住人
操作步骤：

复制代码模板，填入你的API Key
设定户型：model="deepseek-chat"
写需求：messages=[{"role":"user","content":"你的问题"}]
调参数：

temperature：0~1，数值越小答案越严谨（像承重墙），越大越有创意（像装饰墙）

max_tokens:控制回答长度（像控制房间面机）

运行代码，打印结果（验证房子是否能正常使用）

逻辑：先把简单的户型盖好、住通，再去盖复杂户型，避免一步到位搞砸。

第五步：升级施工工具（效率层）

用OpenAI SDK 简化调用

旧工具问题：手写requests 就像“手搬砖、手动砌墙”，慢还容易出错
新工具优势：OpenAI SDK是“电动砌墙机+自动搬砖车”

不用手动拼请求头、解析JSON、SDK全帮你搞定
只改base_url 和model，一套代码能盖Chat、R1甚至其他品牌的AI 户型

操作步骤：

初始化客户端：填Key+改Deepseek地址
调用client.chat.completions.create(), 参数和之前完全一样
直接取completion.choices[0].message.content 拿到答案

逻辑：施工效率升级，核心功能不变，让你更快改好房子、少踩坑。

第六步：加盖大户型（进阶实操层）

调用R1推理模型

户型升级：从Chat小户型 →R1推理大户型（适合复杂需求）
操作差异：只改一个参数，其他代码完全复用

model="deepseek-reasoner"

-适用场景：问"分布解答数学题" "分析景观排水逻辑" "写代码调试" 这类需要深度思考的需求（就像大户型要做复杂的水电布局）

-逻辑：复用之前的地基、墙体和工具，只换户型，体现“代码复用”的工程思维

第七步：装修升级（优化层）

调参+流式输出+多模态

-室内装修（参数调优）：

-智能家电（流式输出）：

-拓展空间（多模态）：把图片转成Base64，传给支持多模态的模型（比如Kimi），让AI 能看图说话（就像给房子加了落地窗，能看到外面的风景）

-逻辑：房子盖好后，通过装修让它更复合你的使用习惯，提升体验。

第八步：学会修房子（排障层）

常见错误与解决方案

-常见故障：

401错误：钥匙丢了/错了→ 区官网重新生成API Key
429错误：施工太频繁，材料不够 → 歇一会儿再调用，或升级额度
500错误：AI 服务器坏了 → 等一会儿再试
答非所问：参数错了 → 核对model名、messages格式

-操作方法：看报错信息→ 对应找原因→ 按方案修复（就像水管漏了先关总阀，再找漏点）

-逻辑：房子住久了会坏，编程也是一样，会修比会盖更重要，保重项目能稳定落地。

第九步：进阶智能改造（工程扩展）

工具调用+Pydantic数据校验

-加装智能家居（工具调用Tool Calls）：

给AI 配"计算机"“查天气”等工具，让它能自动调用工具帮你干活（就像给房子加了智能音箱，能控制家电）

AI判断什么时候用工具 → 调用 → 整理结果给你

-加固房屋结构（Pydantic 校验）：

提前规定AI输出格式（比如必须返回JSON,年龄必须是数字）

自动校验输出，不合格就重来（就像给房子加了抗震结构，保证不会塌）

-逻辑：从"能住的房子"升级成"智能、安全的现代化住宅"，让AI输出能直接被程序使用

总结：

从0到1，用“盖房子”的思路，一步步搭建起一套“高效、稳定、可扩展”的AI 调用体系

先明确目标（盖什么房子）
备齐材料（钥匙+工具）
打牢地基（懂底层原理）
砌墙盖房（先易后难，先Chat后R1）
升级工具（用SDK 提效）
装修优化（调参+体验升级）
学会维修（排障落地）
最后进阶成智能住宅（工具调用+数据校验）

Building Your AI Smart House: A Step-by-Step Analogy for DeepSeek API & OpenAI SDK

You can understand this as a house-building process from zero to moving into a fully functional "AI Smart House".

Every step corresponds to clear knowledge and practical operations:

Step 1: Define the Building Goal (Cognition Layer)

Understand why we need to learn DeepSeek API

The house you’re building:
An "AI Smart House" that automatically calls AI to perform tasks through code.
Two house types:
Chat Model: Daily conversations, copywriting, Q&A (small & simple, easy to use).
**R1 Reasoning Model: **Math problems, logical analysis, complex design (large & powerful).
Core understanding:
API simply means using code to open the door and ask the AI to work.
You don’t need to know how AI works internally — you only need to know how to use it.

Step 2: Prepare Building Materials (Preparation Layer)

Get everything ready before you start building.

Purchase land + get the key:
Register on DeepSeek’s official website and apply for an API Key (your access credential).
Keep it safe and private — like your front door key.
Prepare tools + building materials:
Install Python (your construction team).
Use uv to create a clean virtual environment.
Install required libraries:
requests: **For sending requests to AI.
**openai: Advanced toolkit for simplified API calls.
Logic:
No key = no access.
No tools = no construction.
This step is mandatory.

Step 3: Lay a Solid Foundation (Principle Layer)

Understand the core API logic: Request & Response

Foundation structure:
You send a request → AI processes → AI returns a response
Request includes:
API Key (verify identity)
Model type (deepseek-chat or deepseek-reasoner)
Your question or instruction (messages)
Response format:
Returns structured JSON data
The real answer is inside choices[0].message.content
Practice:
Write a raw request with requests to fully understand how it works.

Step 4: Build the First Wall (Basic Practice Layer)

Start with the simple Chat Model

Operation steps:
Copy the code template and fill in your API Key.
Set model: model="deepseek-chat"
Write your prompt in messages
Adjust parameters: temperature: 0–1 (lower = more precise; higher = more creative) max_tokens: controls answer length
Run code and check the result
Logic:
Master the simple model first, then move to advanced ones.

Step 5: Upgrade Construction Tools (Efficiency Layer)

Use OpenAI SDK to simplify coding

Old way: Manual requests code (slow, error-prone)
New way: OpenAI SDK (automatic, clean, efficient)
Advantages:
No need to build headers or parse JSON
One code set works for all models
Only change base_url and model
Logic:
Work faster, avoid mistakes, keep core functions unchanged.

Step 6: Add the Large House (Advanced Practice Layer)

Use the R1 Reasoning Model

Upgrade:
Chat (small house) → R1 (large, complex house)
Only one change needed:
model="deepseek-reasoner"
Best for:
Math step-by-step solutions, logic analysis, code debugging, complex design.
Logic:
Reuse all previous code — only change the model.

Step 7: Decoration & Upgrade (Optimization Layer)

Improve experience with tuning & advanced features
Parameter tuning: Adjust accuracy, creativity, length
Streaming output: Enable stream=True for real-time word-by-word display
Multi-modal: Convert images to Base64 and let AI “see”
Logic:
Polish your house to fit your habits and make it more powerful.

Step 8: Learn to Repair the House (Troubleshooting Layer)

Fix problems when they happen

Common errors:
401: Wrong/expired API Key → regenerate it
429: Too many requests → wait or upgrade quota
500: Server issue → retry later
Irrelevant answers → check model name & message format
Logic:
Knowing how to fix issues is more important than just building.

Step 9: Advanced Smart Renovation (Engineering Extension)

Make your house intelligent & stable

Tool Calls:
Let AI use calculators, weather tools, and more — like a smart home system.
Pydantic Validation:
Define output format (JSON, numbers, etc.) and auto-validate reliability.
Logic:
Upgrade from a usable house to a safe, smart, production-ready system.

Summary
From 0 to 1, using the house-building mindset to build an:
✅ Efficient
✅ Stable
✅ Scalable
AI integration system.
Define the goal
Prepare materials
Lay the foundation
Build step by step (Chat → R1)
Upgrade tools (SDK)
Decorate & optimize
Learn to repair
Build a real smart house

Building a Production-Ready AI Agent System: From Zero to Hero

caofan99521 — Tue, 24 Mar 2026 06:37:49 +0000

This guide walks you through building an AI Agent system from scratch- one that can think, work, and collaborate in teams. In short, it enables AI to do far more than just chat-it solves complex problems just like a human would.

1. First, equip the AI with a "brain":the LLM module

makd the Ai's “brain” interchageable:switch dynamically between OpenAI, Claude, and more, without modifying the code.
Building a "memory bank"for the AI:store configurations in daabases and use Redis for caching to ensure speed and stability.
Organize tasks into a "pipeline":use message queques to break large tasks into small steps and avoid errors.

2.Teach the AI to "plan and act": the Agent core

Enable the AI to think before acting:create a plan(Plan), execute step by step(Act), and reflect and adjust after competion(ReAct), just like human problem-solving.
Given the AI long-term memory:save past conversations and actions so it doesn't forget.
Let the AI"use tools": call search engines, calculators, and other utilites, just as people browse the web for information.

3.Given the AI"hands and feet": the tool module

Let the AI browse the web: automatically open pages, extract information, take screenshots, and research using browser tools.
integrate various plugins:connect to existing tool ecosystems, anding new features without building from scratch.
Let the AI"write and run code":execute code and read/write files in a secure environment for automated workflows.

4. Build a "sage house"for the Ai: the sandbox module

Prevent the AI from misbehaving by confining it to an isolated "cage"(Docker container), restricting access to the rest of your system.
let the AI operate sagely inside the sandbox: running commands, deleting files, and troubleshooting with one-click reset if issues arise.
Deploy the sandbox as a service so others can use your AI.

5. Enable multiple Als to "work in teams": A2A collaboration

One Ai not enough? Deploy multiple specialized agents: planners, researchers, coders, and more.
Teach them to "communicated and collaborate": exchange messages and assign tasks via the A2A protocol to solve complex problems together.
Build a distributed system so work contunues even if one agent fails

6. Help the AI "never forget": context engineering

Let the AI recall long-past conversations by storing chat history in databases for uninterrupted dialogue.
Enable "review and analysis": review past actions and mistakes for continuous improvement.
Allow task resumption: recover progress even after service restarts.

7. Turn it into a "product": frontend and depoyment

Build web interface for the AI, allowing regular users to chat and watch it work.
Package the entire system into a Docker container for one-click server deployment, making it accessible world wide.
Add monitoring and maintenance to ensure stable, commercial-grade operation.

One-sentence summary: building the AI's brain and teaching it to think, to equipping it with tools and a secure sandbox, enabling multi-AI teamwork,and finally creating a production-ready "super AI assistant".

My Journey Building a Multi-agent System

caofan99521 — Mon, 23 Mar 2026 17:27:57 +0000

这是一套非常完整的多Agent协作系统开发实战课程，核心是教你从底层到上层，从零构建一个工业级的Agent应用框架（基于Manus）

LLM模块开发：让Agent会思考

动态配置LLM提供商（OpenAI、Anthropic等）
用PostgreSQL+Redis做状态检查与消息队列
实现任务拆分、关注点分离的后台Task模块
让Agent能稳定调用不同大模型，处理复杂任务流

Agent 模块开发：让Agent 会规划与行动

核心逻辑：基于Plan&ReAct智能体架构，让Agent 先做规划，再一步步执行、反思调整
多Agent规划步骤与记忆模型设计
LLM结构化输出（Json修复、格式校验）

-工具基类与装饰器开发，让Agent能调用各种工具（搜索、计算等）

通用Agent 配置模型与状态回溯，实现可观测、可调式

3.工具模块开发：给Agent 装上“手脚”

开发搜索引擎工具（Bing、Jina.ai）
集成MCP（Model Context Protocol）工具生态
实现动态增删改工具API,让Agent能够灵活扩展能力
让Agent能像人一样使用外部工具完成复杂任务

Playwright 与BrowserUse：让Agent会上网

用Playwright实现浏览器自动化
让Agent 能浏览网页、提取交互元素、执行JS代码
实现网页截图、滚动、文本输入等操作，让Agent能够处理网页任务

沙箱模块开发：给Agent一个安全的“运行环境”

用Docker 构建隔离沙箱，防止Agent执行危险操作
实现Shell命令执行、文件读写、进程管理
让Agent在安全环境中运行代码、操作系统，避免风险
部署沙箱为独立服务，支持多任务并发

A2A协议集成：让多个Agent 相互协作

Agent-to-Agent（A2A）协议，实现多Agent之间的通信与协作
分布式Agent 系统设计，让多个Agent 分工完成复杂任务
客户端/服务器端管理，让Agent 能互相调用、传递信息

上下文工程：让Agent 记住“过去”

会话数据库设计，让Agent能持久化记忆
消息存储与检索，实现长对话上下文管理
任务流与Agent状态回溯，让Agent 能复盘，优化执行路径

前端与部署：让Agent 变成可使用的产品

用Next.js kai开发前端界面，让用户能和Agent交互
实现聊天UI、任务管理、文件预览等功能
用Docker部署整个系统，实现商业化、高可用
集成VNC 等技术，让用户能实时查看Agent 操作

总结与扩展：工业级Agent开发

项目架构图与开发难点复盘
新增OpenClaw等自动化工具，让Agent更强大

背后逻辑系统：

本质是大模型+工具+记忆+规划+协作的完整闭环：

感知与规划层（plan）

接收用户请求-拆解成可执行的子任务-指定执行计划
用ReAct范式：Reason（推理）-Act（行动）-Observe（观察）-再推理，循环直到任务完成

执行与工具层（Act）

调用LLM生成下一步行动
调用工具（搜索、浏览器、代码执行等）完成具体操作
用沙箱隔离执行环境，保证安全

记忆与状态层（Memory）

用数据库存储会话历史、任务状态、工具调用结果
让Agent能记住之前做过什么，避免重复劳动

-实现状态回溯，方便调试与优化

协作与分布式层（A2A）

多个Agent分工协作：有的负责规划，有的负责执行，有的负责工具调用
通过A2A协议通信，完成复杂的多步骤任务

This is a complete, hands-on course for developing a multi-agent collaboration system. It teaches you how to build an industrial-grade Agent application framework from scratch (based on Manus), from low-level infrastructure to upper-layer services.

LLM Module Development: Make Agents "Think"
Dynamically configure LLM providers (OpenAI, Anthropic, etc.)
Use PostgreSQL + Redis for state management and message queuing
Implement task decomposition and a background Task module with separation of concerns
Enable stable cross-LLM task execution and complex workflow handling
Agent Module Development: Make Agents "Plan & Act"
Core logic: Plan & ReAct architecture — Agents plan first, then execute step-by-step, reflect, and adjust
Design multi-agent planning processes and memory models
Structured LLM output (JSON repair, format validation)
Develop tool base classes and decorators to enable tool use (search, calculation, etc.)
General Agent configuration and state rollback for observability and adjustability
Tool Module Development: Equip Agents with "Hands & Feet"
Develop search engine tools (Bing, Jina.ai)
Integrate the MCP (Model Context Protocol) tool ecosystem
Implement dynamic tool API registration/updates/deletion for flexible capability expansion
Enable Agents to use external tools like humans to complete complex tasks
Playwright & BrowserUse: Make Agents "Browse the Web"
Implement browser automation with Playwright
Enable Agents to navigate pages, extract interactive elements, and execute JavaScript
Support webpage screenshots, scrolling, text input, and web-based task completion
Sandbox Module Development: Build a Safe "Runtime Environment"
Build isolated sandboxes with Docker to prevent risky operations
Support shell execution, file I/O, and process management
Allow Agents to run code and interact with the OS in a secure environment
Deploy sandbox as an independent service for concurrent task support
A2A Protocol Integration: Enable Multi-Agent Collaboration
Agent-to-Agent (A2A) protocol for communication and cooperation
Distributed Agent system design for division-of-labor task completion
Client/server management for cross-Agent invocation and information sharing
Context Engineering: Let Agents "Remember the Past"
Session database design for persistent memory
Message storage & retrieval for long-context dialogue management
Task flow and Agent state rollback for 复盘 (review) and execution optimization
Frontend & Deployment: Turn Agents Into Usable Products
Develop interactive frontend with Next.js
Implement chat UI, task management, file preview, and controls
Deploy the full system with Docker for commercialization and high availability
Integrate VNC for real-time Agent operation monitoring
Summary & Extension: Industrial-Grade Agent Development
Review of system architecture and key development challenges
Extend with tools like OpenClaw for stronger automation capabilities
Underlying System Logic

This is a full closed-loop system:
LLM + Tools + Memory + Planning + Collaboration

Perception & Planning Layer (Plan)
Receive user requests → decompose into executable subtasks → generate execution plans
Follow the ReAct paradigm:
Reason → Act → Observe → Re-reason, repeating until task completion
Execution & Tool Layer (Act)
Call LLM to decide next actions
Invoke tools (search, browser, code execution, etc.) to complete operations
Use sandbox isolation for safe execution
Memory & State Layer (Memory)
Store conversation history, task status, and tool results in databases
Enable Agents to recall prior work and avoid duplication
Support state rollback for debugging and optimization
Collaboration & Distribution Layer (A2A)
Multi-Agent division of labor: planning, execution, tool calling
Communicate via A2A protocol to complete complex multi-step tasks