Chat Completions API

La API de conversación más usada, totalmente compatible con la interfaz Chat Completions de OpenAI.

POST/v1/chat/completionsCrear una conversación de chat

POST https://hub.lurus.cn/v1/chat/completions

Respuesta en streaming

SSE devuelve token a token

Function Calling

Deja que el modelo llame a tus funciones

Vision multimodal

Combina texto e imágenes en la entrada

Mejores prácticas

Temperatura / System Prompt / multironda

---

Parámetros de la solicitud

Obligatorios

Parámetro	Tipo	Descripción
model	string	Nombre del modelo, como deepseek-chat o gpt-4o
messages	array	Arreglo de mensajes de la conversación, ver el formato más abajo

Parámetros opcionales comunes

Parámetro	Tipo	Valor por defecto	Descripción
temperature	number	1.0	Aleatoriedad (0–2). Usa 0.1 para código/matemáticas, 0.9 para escritura creativa
max_tokens	integer	—	Número máximo de tokens a generar. Si no se establece, lo decide el modelo
stream	boolean	false	Salida en streamingStreamingRespuesta en streaming: el modelo de IA devuelve el resultado token a token (en lugar de esperar a generarlo por completo), reduciendo la latencia del primer carácter. (SSE), ver Respuesta en streaming
top_p	number	1.0	Muestreo de núcleo, normalmente se ajusta como alternativa a temperature
stop	string/array	—	Detiene la generación al encontrar esta cadena
n	integer	1	Cuántas respuestas candidatas generar a la vez
user	string	—	Identificador de usuario, usado en los registros de auditoría

Formato de Messages

[
  {"role": "system",    "content": "你是一位专业的技术顾问。"},
  {"role": "user",      "content": "什么是 RESTful API？"},
  {"role": "assistant", "content": "RESTful API 是…"},
  {"role": "user",      "content": "能举个例子吗？"}
]

Rol	Uso
system	Define el comportamiento, el tono y las restricciones de la IA. Va en el primer elemento del arreglo
user	La entrada del usuario
assistant	La respuesta de la IA. En conversaciones multironda hay que incluir las respuestas históricas

La definición completa de todos los campos del cuerpo de la solicitud (ChatCompletionRequest) y del mensaje (Message) se encuentra en la Referencia de estructuras de datos.

---

Ejemplo básico

---

Respuesta en streaming

Establece stream: true y la respuesta se devuelve token a token mediante Server-Sent Events, ideal para aplicaciones de tipo chat.

Formato de los datos en streaming

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"落"},"index":0}]}
data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"叶"},"index":0}]}
...
data: [DONE]

TIP

El último data: [DONE] indica el final del flujo; en ese momento delta.content está vacío.

---

Function Calling

Deja que la IA decida cuándo llamar a las funciones que le proporcionas y devuelva parámetros estructurados (Tool CallTool CallDurante el razonamiento, el modelo de IA decide invocar una herramienta externa (como una búsqueda o una consulta a la base de datos) y devuelve parámetros de invocación estructurados.). Es útil para escenarios como búsquedas, consultas a bases de datos, llamadas a APIs externas, etc.

Flujo de trabajo

Flujo de llamada de Function Calling

graph LR; A[Tu solicitud<br/>con definición de tools] --> B[El modelo devuelve<br/>finish_reason: tool_calls]; B --> C[Ejecutas la función<br/>el resultado se devuelve con role: tool]; C --> D[El modelo combina el resultado<br/>y genera la respuesta final]

Ejemplo completo: consultar el clima

Soporte de modelos

Function Calling requiere que el modelo lo soporte. Se recomienda usar gpt-4o, gpt-4o-mini o claude-3-5-sonnet. La serie DeepSeek también lo soporta, pero el formato de los parámetros tiene diferencias sutiles; verifícalo durante las pruebas.

---

Entrada multimodal (Vision)

Algunos modelos pueden entender el contenido de las imágenes; combina texto e imágenes en el campo content.

Modelos compatibles con Vision

gpt-4o, gpt-4o-mini, gemini-3-pro-preview, gemini-3-pro-image-preview

Límites de tamaño de imagen: las imágenes por URL deben ser accesibles públicamente; para Base64 se recomienda no superar los 5 MB por imagen.

---

Mejores prácticas

Cómo escribir el System Prompt

{
  "role": "system",
  "content": "你是一位专业客服。请用友好简洁的语气回答，每条回复不超过 150 字。如遇无法回答的问题，引导用户联系 support@lurus.cn。"
}

Un buen System Prompt incluye: definición del rol + requisitos de tono + límite de longitud + manejo de los casos límite.

Referencia de ajustes de temperatura

Escenario	temperature	Descripción
Generación de código, cálculo matemático	0.0–0.2	Alta determinación, reduce la aleatoriedad
Preguntas y respuestas, resúmenes, clasificación	0.3–0.6	Preciso pero con cierta flexibilidad
Escritura creativa, lluvia de ideas	0.7–1.0	Gran diversidad
Historias aleatorias, juego de roles	1.0–1.5	Alta creatividad, puede ser inestable

Gestión de conversaciones multironda

conversation = [
    {"role": "system", "content": "你是一位历史老师。"}
]

def chat(user_input: str) -> str:
    conversation.append({"role": "user", "content": user_input})
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=conversation,
        max_tokens=500
    )
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})
    return reply

print(chat("秦始皇是谁？"))
print(chat("他有哪些重要成就？"))  # 模型能记住上文的"秦始皇"

Gestión de la ventana de contexto

Cada modelo tiene una longitud de contexto limitada (por ejemplo, deepseek-chat es de 64K tokens). Cuando la conversación es demasiado larga, puedes:

1. Truncar los mensajes más antiguos (conservar system + las últimas N rondas)
2. Resumir periódicamente la conversación histórica para comprimir el uso de tokens

---

Manejo de errores

Códigos de estado comunes: 400 formato de solicitud incorrecto → revisa la estructura JSON y los parámetros obligatorios; 401 Key inválida/caducada; 403 sin permiso para acceder a este modelo → contacta al administrador; 429 se superó el límite de velocidad → reintenta con retroceso exponencial; 500/502 anomalía del modelo upstream → reintenta o cambia a un modelo de respaldo. Los códigos de error completos y las estrategias de reintento se encuentran en Manejo de errores.

---

Próximos pasos

Manejo de erroresEstructuras de datos / SchemaAutenticaciónDescripción general de la APIModelos compatibles