floship-llm：构建可复用LLM客户端库的工程实践

面向OpenAI兼容推理端点的可复用LLM客户端库，提供标准化接口、错误处理、流式响应、重试机制等生产级功能，简化多模型集成开发。

随着大语言模型生态的蓬勃发展，开发者面临着一个尴尬的现实：每接入一个新的模型提供商，就要重复编写相似的HTTP客户端代码。OpenAI、Anthropic、Google、Cohere、本地部署的vLLM……每个端点都有细微的差异——不同的认证方式、不同的请求格式、不同的错误码、不同的流式响应协议。

这种重复劳动不仅浪费时间，还引入了不一致性。一个项目中同时存在多个风格迥异的LLM客户端，意味着维护成本的倍增和安全风险的累积。当需要切换模型或添加新的提供商时，开发者往往需要在代码库的各个角落进行修改。

floship-llm正是为了解决这一痛点而生。它是一个可复用的LLM客户端库，为OpenAI兼容的推理端点提供统一、健壮、生产就绪的接口抽象。

构建一个通用的LLM客户端库面临核心张力：一方面需要提供统一的接口以简化使用，另一方面需要保留足够的灵活性以适应不同提供商的特性。floship-llm的设计在两者之间找到了平衡点。

项目选择OpenAI API作为兼容性基线，这是一个务实的决定。OpenAI的API设计已成为事实上的行业标准，从开源的vLLM、TGI到商业的Azure OpenAI、Anthropic的兼容模式，都遵循这一规范。以OpenAI为基线意味着最大的生态兼容性。

尽管以OpenAI为基线，floship-llm并不假设所有端点完全遵循这一规范。库的设计支持提供商特定的适配器，处理认证差异、端点路径差异、响应格式差异等。这种适配器模式让核心代码保持简洁，同时为特殊需求留出扩展空间。

现代Python开发越来越重视类型安全。floship-llm提供完整的类型注解，让IDE能够提供准确的自动补全和类型检查。请求参数、响应结构、错误类型都有明确的类型定义，减少运行时错误，提升开发体验。

floship-llm不仅仅是一个HTTP包装器，它提供了一系列生产环境必需的功能。

库暴露的核心接口遵循OpenAI SDK的约定，包括：

• Chat Completions：对话补全，支持多轮对话和工具调用
• Embeddings：文本向量化，用于RAG和语义搜索
• Completions：文本补全（传统接口，向后兼容）

统一的方法签名意味着开发者可以在不同提供商之间无缝切换，只需更改配置而非代码。