人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用【免费下载链接】KilnBuild, Evaluate, and Optimize AI Systems. Includes evals, RAG, agents, fine-tuning, synthetic data generation, dataset management, MCP, and more.项目地址https://gitcode.com/gh_mirrors/ki/Kiln点击查看免费下载本篇指南面向需要以 Python 程序访问 Kiln AI FastAPI 服务的开发者围绕仓库中自动生成的官方客户端库kiln_ai_server_client展开覆盖客户端创建、同步/异步四种调用形态、SSL 证书策略、模块组织规则、底层 httpx 定制并结合仓库内桌面端的真实工厂函数与测试用例给出可直接落地的调用方案。读完本文你将能够在自己项目中快速接入 Kiln AI Server 的鉴权、健康检查、聊天与会话等端点。客户端库概览与目录结构kiln_ai_server_client位于仓库的 app/desktop/studio_server/api_client/kiln_ai_server_client 目录是一个用于访问 Kiln AI FastAPI Service 的 Python 客户端库。它的README.md 开篇即有一句重要提醒Important: This folder is automatically generated. Do not make any edits, they will be replaced on next generation.也就是说该目录由 OpenAPI 文档自动生成属于 openapi-python-client 风格的生成产物任何手工修改都会在下次重新生成时被覆盖。因此在日常开发中应该把它当作“只读依赖”使用把自定义逻辑放在自己的业务代码里。从仓库文件结构可以确认其典型布局client.py核心的Client与AuthenticatedClient类定义types.py共享类型包括Response、File、UNSET、Unset等errors.py异常类型如UnexpectedStatusapi/按 OpenAPI tag 划分的端点函数模块auth、chat、copilot、health、jobs、synthetic_user 等models/请求/响应的数据模型如ChatRequest、ApiKeyVerificationResult__init__.py对外导出AuthenticatedClient与Client见init.pypy.typed类型标记文件表明该包提供类型提示支持。快速开始创建客户端约定所有需要鉴权的端点都应使用AuthenticatedClient它会在底层 httpx 客户端上自动附加 Authorization 头。最简单的用法是直接指定服务地址与 API Keyfrom kiln_ai_server_client import AuthenticatedClient client AuthenticatedClient(base_urlhttps://api.kiln.tech, tokenKILN_API_KEY)然后调用端点函数并使用返回的数据模型from kiln_ai_server_client.models import MyDataModel from kiln_ai_server_client.api.my_tag import get_my_data_model from kiln_ai_server_client.types import Response with client as client: my_data: MyDataModel get_my_data_model.sync(clientclient) # 或者当你需要更多信息例如 status_code时 response: Response[MyDataModel] get_my_data_model.sync_detailed(clientclient)异步版本的写法完全对称只需把with换成async with把sync换成asynciofrom kiln_ai_server_client.models import MyDataModel from kiln_ai_server_client.api.my_tag import get_my_data_model from kiln_ai_server_client.types import Response async with client as client: my_data: MyDataModel await get_my_data_model.asyncio(clientclient) response: Response[MyDataModel] await get_my_data_model.asyncio_detailed(clientclient)从源码看Client与AuthenticatedClient都是基于attrs定义的类见 client.py并实现了__enter__/__exit__与__aenter__/__aexit__上下文管理器协议分别代理内部httpx.Client与httpx.AsyncClient的生命周期。官方 httpx 文档也提醒同一个客户端实例不能重复进入上下文管理器两次。四种调用形态sync / sync_detailed / asyncio / asyncio_detailed客户端库的设计遵循一个统一约定每个路径/方法组合都会生成一个 Python 模块模块内固定提供四个函数函数特性适用场景sync阻塞式请求成功时返回解析后的数据parsed否则返回None简单脚本、一次性任务sync_detailed阻塞式请求始终返回Response对象成功时其parsed字段被填充需要状态码、原始内容、响应头时asyncio与sync相同语义但基于异步而非阻塞异步事件循环内的快速调用asyncio_detailed与sync_detailed相同语义但基于异步异步场景下需要完整响应信息以仓库中的健康检查端点为例ping_ping_get.py 中sync的实现就是把sync_detailed(...).parsed返回给调用方asyncio则对应await asyncio_detailed(...)的parsed。这种“detail 变体 parsed 取值”的分层结构贯穿所有端点函数掌握后即可举一反三。Response对象本身定义在 types.py包含四个字段status_codehttp.HTTPStatus枚举content原始响应字节headers响应头parsed解析后的数据模型未成功时为None。SSL 证书验证策略默认情况下调用 HTTPS API 时客户端会校验 SSL 证书官方强烈建议在绝大多数场景下保持证书验证开启。但某些场景尤其是内网服务器或自签名证书环境需要自定义证书client AuthenticatedClient( base_urlhttps://internal_api.example.com, tokenSuperSecretToken, verify_ssl/path/to/certificate_bundle.pem, )也可以彻底关闭证书校验但请注意这是一种安全风险client AuthenticatedClient( base_urlhttps://internal_api.example.com, tokenSuperSecretToken, verify_sslFalse )从 client.py 的字段定义可以看出verify_ssl的类型为str | bool | ssl.SSLContext默认值为True——既支持字符串证书路径也支持布尔开关甚至可以传入构造好的ssl.SSLContext实例进行更细粒度的控制。该值最终会被透传给底层 httpx 客户端的verify参数见 client.py。模块组织与函数命名规则理解生成代码的组织规则可以帮助你快速定位任意端点每个路径/方法组合对应一个 Python 模块模块内含sync、sync_detailed、asyncio、asyncio_detailed四个函数如上节所述所有路径参数、查询参数以及请求体都变成函数的参数如verify_api_key的client、handle_chat的body、check_entitlements的feature_codes如果端点带有 tag则第一个 tag会被用作函数所在模块的目录名例如my_tag对应api.my_tag没有任何 tag 的端点统一放在kiln_ai_server_client.api.default中。对照仓库实际的api/目录可以验证这一规则auth/鉴权与 entitlement 检查、chat/聊天与会话管理、copilot/Copilot 系列批量生成与规格优化、health/健康检查、jobs/异步任务状态与结果、synthetic_user/合成用户生成等模块全部与 OpenAPI tag 一一对应。高级定制深入 httpx 层生成出的Client类还提供了更多运行时行为控制项完整的参数清单见该类的 docstringclient.py包括base_urlAPI 基础地址所有请求都相对该地址拼接路径cookies随每次请求发送的 Cookie 字典headers随每次请求发送的头字典timeout单次请求的超时上限超时抛出httpx.TimeoutExceptionverify_ssl是否校验服务端 SSL 证书生产环境建议为True测试环境可设为Falsefollow_redirects是否跟随重定向默认Falsehttpx_args透传给httpx.Client与httpx.AsyncClient构造函数的额外参数raise_on_unexpected_status当服务端返回 OpenAPI 文档未记载的状态码时是否抛出errors.UnexpectedStatus默认False。通过 httpx_args 挂载事件钩子最常见的定制需求是观测请求生命周期可以通过httpx_args的event_hooks实现from kiln_ai_server_client import Client def log_request(request): print(fRequest event hook: {request.method} {request.url} - Waiting for response) def log_response(response): request response.request print(fResponse event hook: {request.method} {request.url} - Status {response.status_code}) client Client( base_urlhttps://api.example.com, httpx_args{event_hooks: {request: [log_request], response: [log_response]}}, )事件钩子由 httpx 原生支持这里只是通过httpx_args原样传递。直接操作底层 httpx 客户端还可以通过client.get_httpx_client()或client.get_async_httpx_client()拿到底层客户端直接修改。甚至可以整体替换底层的 httpx 客户端——但注意这会覆盖已有设置包括 base_urlimport httpx from kiln_ai_server_client import Client client Client( base_urlhttps://api.example.com, ) # 注意 base_url 需要重新设置共享的 cookies、headers 等同样需要重新传入 client.set_httpx_client(httpx.Client(base_urlhttps://api.example.com, proxieshttp://localhost:8030))从 client.py 的实现可以看到set_httpx_client直接替换内部_client字段而get_httpx_client在尚未构造时按base_url、cookies、headers、timeout、verify、follow_redirects以及httpx_args惰性创建。不可变式派生with_headers / with_cookies / with_timeout除了直接修改Client与AuthenticatedClient还提供了基于attrs.evolve的派生方法with_headers(...)、with_cookies(...)、with_timeout(...)会返回一个携带新配置的新客户端实例同时若底层 httpx 客户端已创建还会同步更新其对应属性见 client.py。这种模式适合在不污染全局实例的前提下为单次请求注入额外头或调整超时。仓库内的真实用法工厂函数与请求级定制生成目录之外的 kiln_server_client.py 展示了该客户端库在 Kiln 桌面端内部的实际集成方式值得作为最佳实践参考环境变量覆盖服务地址_get_base_url()读取KILN_SERVER_BASE_URL环境变量缺省回退到https://api.kiln.tech统一公共头_get_common_headers()注入User-Agent: KilnDesktopApp/{version}与Kiln-Desktop-App-Version两个头便于服务端识别客户端版本鉴权客户端工厂get_authenticated_client(api_key)构造携带 API Key 的AuthenticatedClient并为长耗时请求设置了httpx.Timeout(timeout900.0, connect30.0)——读超时 900 秒、连接超时 30 秒适配 Copilot 批量生成等长任务OAuth 客户端工厂get_oauth_authenticated_client(access_token)用于用户已完成 Kinde OAuth 登录但尚未取得 Kiln API Key 的注册前阶段通过把 access_token 作为 token 传入复用同一套鉴权机制单例复用模块级变量server_client get_kiln_server_client()作为无鉴权客户端的默认实例避免重复创建。在业务层chat/routes.py 中代理 Kiln Copilot 会话列表时正是先调用get_authenticated_client(api_key)拿到客户端再通过list_sessions_v1_chat_sessions_get.asyncio_detailed(clientclient, limitlimit, ...)发起异步调用settings_api.py 则引入了check_entitlements_v1_check_entitlements_get用于校验用户组织的功能权益。这些调用模式与 README 的文档完全一致可作为端到端参考。典型端点实战示例以下结合仓库真实生成的端点函数给出可直接运行的示例。健康检查GET /pingfrom kiln_ai_server_client.api.health import ping_ping_get from app.desktop.studio_server.api_client.kiln_server_client import get_kiln_server_client client get_kiln_server_client() result ping_ping_get.sync(clientclient) # 返回字符串 pong response ping_ping_get.sync_detailed(clientclient) print(response.status_code, response.parsed) # 200 pong该端点定义见 ping_ping_get.py适用于基础连通性测试与负载均衡健康检查。校验 API KeyGET /v1/verify_api_keyfrom kiln_ai_server_client.api.auth import verify_api_key_v1_verify_api_key_get from app.desktop.studio_server.api_client.kiln_server_client import get_authenticated_client client get_authenticated_client(KILN_API_KEY) result verify_api_key_v1_verify_api_key_get.sync(clientclient) # result 为 ApiKeyVerificationResult其 is_valid 字段表示密钥是否有效实现见 verify_api_key_v1_verify_api_key_get.py。成功200时返回ApiKeyVerificationResultis_valid布尔字段定义见 models/api_key_verification_result.py未授权401时返回UnauthorizedResponse。发送聊天请求POST /v1/chat/from kiln_ai_server_client.api.chat import handle_chat_v1_chat_post from kiln_ai_server_client.models import ChatRequest, ClientChatMessage, ClientChatMessageRole from app.desktop.studio_server.api_client.kiln_server_client import get_authenticated_client client get_authenticated_client(KILN_API_KEY) body ChatRequest( messages[ ClientChatMessage(roleClientChatMessageRole.USER, contentHello Kiln Copilot!), ] ) result handle_chat_v1_chat_post.sync(clientclient, bodybody)实现见 handle_chat_v1_chat_post.py请求体模型ChatRequestmessages必填、trace_id可选定义在 models/chat_request.py消息角色模型位于 models/client_chat_message_role.py。校验功能权益GET /v1/check_entitlementsfrom kiln_ai_server_client.api.auth import check_entitlements_v1_check_entitlements_get from app.desktop.studio_server.api_client.kiln_server_client import get_authenticated_client client get_authenticated_client(KILN_API_KEY) result check_entitlements_v1_check_entitlements_get.sync( clientclient, feature_codescode1,code2, # 逗号分隔的权益 feature code 字符串 )实现见 check_entitlements_v1_check_entitlements_get.pyfeature_codes以查询参数形式传递返回以每个 feature code 为键、布尔值为值的 JSON 对象。错误处理机制每个端点函数都会按 OpenAPI 文档中声明的状态码逐一解析响应例如handle_chat会分别处理 200、400、401、404、422、426、500见 handle_chat_v1_chat_post.py。当遇到文档中未声明的状态码时行为取决于raise_on_unexpected_status为False默认时parsed返回None不抛异常为True时抛出 errors.py 中定义的errors.UnexpectedStatus异常对象携带status_code与content两个属性便于诊断。此外当请求超过Client.timeout配置时会抛出httpx.TimeoutException这与 httpx 的行为保持一致。测试验证客户端行为有据可查仓库为客户端工厂函数提供了完整的单元测试test_kiln_server_client.py可用来验证本文中的各项行为描述test_returns_client_with_correct_base_url_no_env_var与带环境变量的对应测试确认KILN_SERVER_BASE_URL的覆盖逻辑test_returns_client_with_correct_user_agent_header、test_client_creates_httpx_client_with_correct_headers确认User-Agent与Kiln-Desktop-App-Version头从构造参数正确透传到 httpx 客户端test_ping_sync、test_ping_returns_pong_using_sync_helper通过MagicMock替换底层 httpx 客户端验证ping_ping_get.sync与sync_detailed的调用路径与返回值TestAsyncPingRequest用httpx.MockTransport模拟异步传输验证asyncio变体与 User-Agent 头TestGetAuthenticatedClient系列验证鉴权客户端的 token、base_url、900 秒读超时与 30 秒连接超时等配置标记为paid的TestRealPingRequest则是面向真实服务的冒烟测试服务未运行时失败因此被排除在常规测试之外。结语kiln_ai_server_client是一个由 OpenAPI 规范自动生成、以 httpx 为底层、覆盖 Kiln AI FastAPI 服务全部端点的类型安全客户端库。理解其“四函数一模块”的组织约定、AuthenticatedClient的鉴权注入方式以及httpx_args/set_httpx_client等定制入口就能在自己的 Python 项目中以极少的样板代码完成同步或异步调用。仓库中 kiln_server_client.py 的工厂函数统一 base_url、公共头、长超时、OAuth 支持则是生产级集成的成熟范式可直接参考复用。若需深入某个端点的具体参数与响应结构建议结合服务端 OpenAPI 文档与api/、models/目录下的生成代码逐一对照。赞分享人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用【免费下载链接】KilnBuild, Evaluate, and Optimize AI Systems. Includes evals, RAG, agents, fine-tuning, synthetic data generation, dataset management, MCP, and more.项目地址https://gitcode.com/gh_mirrors/ki/Kiln点击查看免费下载相关推荐HelixDB Python SDK 使用指南查询 DSL、同步/异步客户端与嵌入式数据库实战HelixDB Python SDK 使用指南查询 DSL、同步/异步客户端与嵌入式数据库实战 HelixDB 是一款基于 Rust 构建、面向对象存储的 O数据库图数据库向量数据库AI 应用RAGLettuce 高级 Java Redis 客户端快速上手同步、异步与响应式 API 实战指南Lettuce 高级 Java Redis 客户端快速上手同步、异步与响应式 API 实战指南 Lettuce 是一个可扩展、线程安全的 Java Redis数据库后端缓存Kubernetes Python 客户端 OpenidApi 使用指南通过异步/同步 API 获取 Service Account Issuer OpenID JWKSKubernetes Python 客户端 OpenidApi 使用指南通过异步/同步 API 获取 Service Account Issuer OpenI后端云原生容器编排创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考