最近 AI 圈又迎来一个备受关注的消息林俊旸官宣创业公司 Pragmatik Labs。虽然公开信息里还没有太多关于具体产品的细节但从“Pragmatik务实”这个词以及当前 AI 创业的节奏来看这类公司大概率会聚焦在大模型应用落地、Agent 系统、企业级 AI 基础设施或者垂直行业的 AI 解决方案上。对于大多数开发者来说大家真正关心的可能不是新闻本身而是如果我要加入一家类似的 AI 创业公司或者自己打算从零搭建一个 AI 应用技术栈到底该怎么选架构怎么设计哪些坑是必须提前避开的这篇文章我就结合 Pragmatik Labs 这类 AI 创业公司的常见技术方向从一个后端开发者的视角完整梳理一套“LLM 应用从 0 到 1 落地”的工程化方案。内容会覆盖技术选型、环境准备、完整实战案例、常见报错排查以及工程最佳实践。无论你是想入门 AI 应用开发还是正在企业里做技术预研这篇都能给你一条可以照着走的路线。1. 背景AI 创业公司与 LLM 应用工程化1.1 为什么“务实”的 AI 应用需要工程化思维很多人对 AI 创业的第一印象是“训练大模型”但真正能快速产生业务价值的往往是把现有大模型能力封装成稳定、可控、安全的业务系统。这中间的差距就是工程化能力。一个真实可用的 AI 应用至少包含以下环节模型接入与统一网关。提示词Prompt管理与版本控制。知识库的切片、向量化与检索。Agent 工具调用与流程编排。流式输出的前端对接。可观测性与成本控制。安全与权限治理。也就是说哪怕你的核心代码只有几十行调用大模型 API 的逻辑把它变成能支撑真实用户访问的系统仍然有大量的工程工作要做。Pragmatik Labs 这类公司如果要走“务实”路线大概率会在这些方向里选一个垂直点做深。1.2 LLM 应用与传统后端开发的差异传统后端开发的核心是“确定性的逻辑”请求进来经过业务校验、数据库读写、返回结果。LLM 应用的核心则是“非确定性的生成”模型输出会有随机性同样的 Prompt 可能得到不同结果。这个差异带来以下几个必须重新思考的问题输出校验不能假设模型返回的一定是合法 JSON必须做二次解析与容错。超时控制模型推理耗时长接口需要支持流式输出和合理的超时策略。成本与限流Token 消耗就是成本需要对用户请求做配额管理。缓存策略相似问题可以走缓存降低模型调用量和延迟。提示词即代码Prompt 需要像代码一样走评审、测试和版本发布流程。理解了这些差异你就能明白为什么 AI 应用开发不能只停留在“调 API 跑通 Demo”而需要一套完整的工程体系。2. 环境准备与版本说明2.1 运行时与语言选择本文的实战案例以 Python 3.10 为例因为当前 LLM 生态里 Python 的 SDK 支持最完整。但实际生产环境中Java、Go、Node.js 也完全可以承担这一层关键看团队的技术栈积累。版本方面不写死具体依赖原因是这个生态迭代非常快。你只需要确保Python 3.10 及以上。pip 可以正常安装第三方包。有可访问的大模型 API 服务例如 OpenAI 兼容接口、国内云厂商的模型服务或者本地通过 Ollama 部署的开源模型。如果你本地的网络环境对某些 API 域名访问不稳定建议优先选择国内服务商的兼容接口或者提前准备好可用的 API 网关配置。2.2 项目基础依赖创建一个虚拟环境并安装以下核心依赖python -m venv venv source venv/bin/activate # Windows 下执行 venv\Scripts\activatepip install fastapi uvicorn openai pydantic python-dotenv这些依赖各自的作用fastapi提供高性能的异步 API 服务。uvicornFastAPI 的 ASGI 服务器。openai官方 Python SDK兼容 OpenAI 格式的接口。pydantic数据校验与配置管理。python-dotenv加载.env配置文件。2.3 推荐的项目结构pragmatik-demo/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 入口 │ ├── config.py # 配置管理 │ ├── models.py # 数据模型 │ ├── llm.py # 大模型调用封装 │ └── prompt.py # 提示词模板 ├── .env.example # 环境变量示例 ├── requirements.txt # 依赖清单 └── README.md这个结构足够清晰也方便后续扩展知识库、Agent、缓存等模块。3. 核心架构与技术选型拆解3.1 模型接入层接入大模型的第一步是抽象一个统一的 LLM 客户端。这样后续无论切换模型服务商还是同一个服务商的不同模型版本业务代码都不需要改动。一个最小可用的封装长这样# 文件路径app/llm.py import os from openai import OpenAI class LLMClient: def __init__(self): self.client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), ) self.model os.getenv(LLM_MODEL) def chat(self, messages, temperature0.3, max_tokens1024, streamFalse): response self.client.chat.completions.create( modelself.model, messagesmessages, temperaturetemperature, max_tokensmax_tokens, streamstream, ) return response这里的base_url和model都从环境变量读取意味着你可以在部署时通过配置切换不同的模型服务而不需要重新发布代码。有一点需要注意temperature参数控制输出的随机性。如果是客服问答、代码生成这类需要稳定结果的场景建议调低到 0.1-0.3如果是创意写作、头脑风暴可以调到 0.7 以上。3.2 提示词管理提示词是 LLM 应用最核心的“代码”。实际项目中建议把提示词模板集中管理而不是散落在业务代码里。# 文件路径app/prompt.py SYSTEM_PROMPT 你是一个专业的企业知识库助手。 你的职责是根据给定的参考资料回答用户的问题。 要求 1. 如果参考资料中没有答案明确告知用户“知识库中暂未找到相关内容”。 2. 不要编造不存在的信息。 3. 回答尽量结构化使用小标题和列表。 4. 只使用中文回答。 def build_messages(query: str, context: str) - list: return [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: f参考资料\n{context}\n\n用户问题{query}}, ]设计提示词时有几个工程上的经验系统提示词固定不变把角色设定和回答规则放在 system 里避免用户通过输入覆盖。参考资料与用户问题用明确分隔符区分例如参考资料和用户问题方便模型区分指令与数据。用户输入要转义处理防止用户通过注入内容改变模型行为例如输入“忽略上面的指令”。3.3 知识库与检索增强生成RAG企业级 AI 应用通常不能只靠模型自身的知识而是要把企业的文档、规范、历史工单等私有数据注入到回答中。这就用到 RAGRetrieval-Augmented Generation架构。RAG 的核心流程是把文档切片。对切片做向量化处理。用户提问时把问题也做向量化。在向量数据库中检索相似度最高的切片。把检索结果拼接到提示词中让模型基于这些内容回答。这里不引入完整的向量数据库比如 Milvus、Weaviate先用内存里的简单示例说明原理# 文件路径app/rag.py import numpy as np class SimpleVectorStore: def __init__(self): self.texts [] self.vectors np.array([]).reshape(0, 0) def add_text(self, text: str, embedding): # 实际项目中 embedding 由模型接口生成 vector np.array(embedding).reshape(1, -1) if self.vectors.shape[1] 0: self.vectors vector else: self.vectors np.vstack([self.vectors, vector]) self.texts.append(text) def search(self, query_embedding, top_k3): query_vec np.array(query_embedding).reshape(1, -1) scores np.dot(self.vectors, query_vec.T).flatten() top_indices scores.argsort()[-top_k:][::-1] return [self.texts[idx] for idx in top_indices]真实项目中向量化接口、向量数据库的选型、切片的粒度都会影响检索效果。切片太大会带进来很多无关内容切片太小又会丢失上下文一般需要根据文档类型反复调优。3.4 Agent 工具调用当 LLM 应用需要执行具体操作比如查询数据库、调用外部 API、发送消息时就需要引入 Agent 机制。核心思路是让模型决定“调用哪个工具、传入什么参数”然后由程序执行工具并返回结果给模型。工具注册可以这样设计# 文件路径app/tools.py import json def get_weather(city: str) - str: 模拟获取天气的工具实际项目中替换为真实 API 调用 return json.dumps({city: city, weather: 晴, temperature: 22}) TOOLS [ { type: function, function: { name: get_weather, description: 获取指定城市的当前天气, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city], }, }, } ]在对话循环中模型如果判断需要查询天气会返回一个工具调用请求程序解析后调用get_weather再把结果追加到消息列表中继续请求模型。这一块的工程复杂度明显高于单纯的问答因为涉及工具结果解析、错误处理、多轮上下文管理以及最头疼的“模型陷入循环调用”问题。3.5 流式输出用户对大模型应用最直接的体验就是“打字机效果”。FastAPI 里可以通过 SSEServer-Sent Events实现。from fastapi.responses import StreamingResponse app.post(/chat/stream) async def chat_stream(request: ChatRequest): def generate(): # 这里实际上应该调用 llm.chat(streamTrue) 并逐 block 产出 for chunk in [你好, , 我是, AI助手, 。]: yield fdata: {chunk}\n\n return StreamingResponse(generate(), media_typetext/event-stream)注意真实项目中流式响应还需要处理客户端断开连接、异常中断、超时等问题不是简单一个生成器就能覆盖的。4. 完整实战案例搭建一个企业知识库问答服务前面讲了很多概念这一节我用一个完整的案例把知识串起来。需求很简单实现一个带知识库检索的 FAQ 问答接口。4.1 需求分析用户传入一个问题。系统从本地知识库中检索相关内容。LLM 基于检索结果生成回答。接口返回答案和检索到的参考资料。这个场景是知识库问答的最小闭环也是很多 AI 创业公司第一个落地的功能。4.2 配置环境变量# 文件路径.env.example LLM_API_KEYyour_api_key LLM_BASE_URLhttps://api.example.com/v1 LLM_MODELgpt-4o-mini注意.env.example只是模板真正的.env文件不要提交到 Git 仓库。4.3 编写配置模块# 文件路径app/config.py import os from dotenv import load_dotenv load_dotenv() class Settings: llm_api_key: str os.getenv(LLM_API_KEY, ) llm_base_url: str os.getenv(LLM_BASE_URL, ).rstrip(/) llm_model: str os.getenv(LLM_MODEL, ) settings Settings()4.4 编写数据模型# 文件路径app/models.py from pydantic import BaseModel class ChatRequest(BaseModel): query: str class ChatResponse(BaseModel): answer: str references: list[str]4.5 编写知识库初始化和检索逻辑这里用简单的列表模拟检索结果真实项目中通常会接向量数据库。# 文件路径app/main.py 中的简化逻辑 KNOWLEDGE_BASE [ Pragmatik Labs 是一家 AI 创业公司聚焦大模型应用落地。, RAG 架构通过检索增强生成可以显著减少模型幻觉。, 提示词管理在 AI 工程中非常重要需要像代码一样进行版本控制。, 流式输出可以显著提升用户等待大模型回复时的体验。, ] def simple_retrieve(query: str, top_k: int 2) - list[str]: # 真实项目中这里会把 query 向量化后在向量数据库里做相似度检索 # 这里做一个简单的关键词过滤演示逻辑 matched [] for text in KNOWLEDGE_BASE: if query in text or any(word in text for word in query.split()): matched.append(text) return matched[:top_k]4.6 补全主程序# 文件路径app/main.py from fastapi import FastAPI from app.config import settings from app.llm import LLMClient from app.models import ChatRequest, ChatResponse from app.prompt import build_messages app FastAPI(titlePragmatik Demo API) llm LLMClient() app.get(/health) async def health(): return {status: ok} app.post(/chat, response_modelChatResponse) async def chat(req: ChatRequest): if not req.query: return ChatResponse(answer问题不能为空, references[]) # 1. 检索相关上下文 refs simple_retrieve(req.query) # 2. 构造提示词 context \n\n.join(refs) if refs else 知识库中没有找到相关信息。 messages build_messages(req.query, context) # 3. 调用大模型 resp llm.chat(messages) return ChatResponse(answerresp.choices[0].message.content, referencesrefs) if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)4.7 运行与验证启动服务uvicorn app.main:app --reload --port 8000调接口curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {query: 什么是 RAG 架构}预期返回格式{ answer: RAG 架构通过检索增强生成可以在回答时引用外部知识库内容减少模型幻觉……, references: [ RAG 架构通过检索增强生成可以显著减少模型幻觉。 ] }到这里一个最小的知识库问答服务就跑通了。后续你可以把simple_retrieve替换成真正的向量检索把列表型知识库替换成文档解析管道就具备了一个企业级问答系统的雏形。5. 常见问题与排查思路5.1 常见报错汇总问题现象常见原因解决思路AuthenticationErrorAPI Key 配置错误或已过期检查.env中LLM_API_KEY确认没有多余空格ConnectionError网络无法访问模型服务检查base_url确认服务商在本地网络下可直连返回内容总是 JSON 解析失败模型输出不是合法 JSON在提示词里强制 JSON 格式并对返回结果做二次兜底解析检索结果与问题无关切片粒度不合理或检索算法不匹配调整切片大小、换用向量检索、加入重排Rerank策略接口响应特别慢模型本身推理耗时长或检索链路太长使用流式输出、加缓存、对长文本做精简模型回答“编造”事实知识库没有相关内容且未做拒答设计在系统提示词中明确要求“查不到就直说”并加入知识库兜底逻辑5.2 最容易踩的三个坑第一个坑直接把用户输入拼进提示词而不做过滤。如果用户输入包含“忽略以上指令”之类的注入内容模型的回答可能完全偏离系统设定。解决方案是对用户输入做长度限制并且在提示词中明确区分“指令区”和“数据区”。第二个坑盲目追求大模型版本忽略成本控制。很多场景下小模型配合好的提示词和检索效果完全能替代大模型。生产环境建议设置单用户每日 Token 配额防止恶意调用导致账单失控。第三个坑没有日志和可观测性。LLM 应用的排查比传统后端困难得多因为你无法直接断点调试模型的“思考过程”。必须记录每次请求的输入输出、Token 消耗、延迟、模型版本否则线上出问题根本无从下手。5.3 排查清单按下面的顺序排查问题效率最高检查 API Key 与网络连通性。检查模型名称是否在当前服务商可用列表中。用最小请求单独测试模型接口确认模型本身是否正常。依次关闭知识库、工具调用二分定位问题出在哪一层。查看日志中的 Prompt 原文确认是否有内容污染。确认输出解析逻辑是否能处理模型返回的异常格式。6. 最佳实践与工程建议6.1 提示词按版本管理把提示词模板提交到 Git 仓库和代码一起走评审、测试、发布流程。如果有条件最好给每个提示词做版本号线上出问题时可以快速回退到旧版本。6.2 配置与环境隔离API Key、模型名称、base_url 等全部走环境变量或配置中心不要硬编码在代码里。不同的环境开发、测试、生产使用不同的服务和模型避免本地调试时误连生产环境接口。6.3 统一异常处理与超时策略模型调用一定要设置超时时间推荐 30-60 秒。对于非流式接口如果超过时间模型还没返回应该主动中断并通知客户端稍后重试。同时要把所有外部依赖模型服务、数据库、向量库的异常包装成统一的内部错误避免原始错误信息暴露给前端。6.4 Token 与成本治理在网关层做 Token 统计和配额控制可以按照用户、部门、项目等维度分别计量。对于内容差异不大的请求可以加一层语义缓存利用模型生成的 embedding 做相似度判断命中缓存就直接返回历史答案能省下很大一部分模型调用费用。6.5 安全边界生产环境一定要做好以下安全防护用户输入长度与频率限制。Prompt 注入检测与过滤。输出内容敏感词过滤。知识库权限隔离确保普通用户不能检索到内部敏感文档。模型服务端点的访问鉴权不能让未认证用户直接调用你的后端代理。6.6 可观测性推荐记录以下核心指标每次请求的完整输入输出脱敏后。Prompt 版本号与模型版本。Token 消耗与成本估算。请求耗时分布。检索命中率与回答质量评分可以人工抽评。数据量上来之后这些指标就是评估系统健康度和优化方向最重要的依据。6.7 工程上的渐进式架构不要一开始就追求完整的 Agent 平台、知识库平台、模型网关。推荐按业务需求的优先级逐步迭代第一阶段单模型 简单提示词 流式输出。第二阶段引入知识库与向量检索解决私有知识问答。第三阶段引入工具调用与 Agent 编排处理复杂任务。第四阶段完善可观测性、成本治理、权限体系支撑规模化用户。每一阶段都保证线上可运行、可回退不要一上来就搞一个过度复杂的系统。7. 收尾从 Demo 到生产力的关键一步回到 Pragmatik Labs 和 AI 创业公司的话题。无论是大厂背景的研究者还是草根开发者今天做 AI 应用的门槛其实已经被大幅拉低了。真正拉开差距的不是谁先调通了模型 API而是谁能把 Demo 变成一个稳定、安全、成本可控的生产系统。这套能力不是靠看几篇新闻就能掌握的需要你在真实项目里反复验证和积累。如果你正打算进入这个方向建议先从本文的知识库问答案例开始把它部署到服务器上加上流式输出、加上日志、加上权限校验一步一步把“能用”变成“好用”。如果你对 Agent 编排、向量数据库选型、模型微调这些方向感兴趣可以继续深入实践。这个过程里遇到的具体问题往往比任何教程都更有价值。