iop/docs/dev-corp-openai-compatible-call-guide.md

dev-corp OpenAI-Compatible Call Guide

dev-corp gemma4:26b 모델을 OpenAI-compatible 방식으로 직접 호출할 때 필요한 최소 설정이다.

기본값

항목	값
Base URL	http://digitalplatform-iop.cloud:18086/v1
Chat endpoint	POST /v1/chat/completions
Models endpoint	GET /v1/models
Model	gemma4:26b
Auth header	Authorization: Bearer <token>

/v1/responses가 아니라 /v1/chat/completions를 사용한다.

Pi 설정

현재 호스트의 Pi dev-corp profile은 ~/.pi/agent/settings.json과 ~/.pi/agent/models.json을 기준으로 한다.

필수 기본값:

항목	값
defaultProvider	dev-corp
defaultModel	gemma4:26b
defaultThinkingLevel	high
extensions	extensions/dev-corp-temperature.ts

Pi 0.80.3의 models.json provider/model schema에는 고정 sampling parameter 필드가 없다. dev-corp Pi 호출의 temperature와 top_p는 전역 extension ~/.pi/agent/extensions/dev-corp-temperature.ts의 before_provider_request hook에서 적용한다.

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

const DEV_CORP_PROVIDER = "dev-corp";
const DEV_CORP_TEMPERATURE = 0.2;
const DEV_CORP_TOP_P = 0.95;

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

export default function (pi: ExtensionAPI) {
  pi.on("before_provider_request", (event, ctx) => {
    if (ctx.model?.provider !== DEV_CORP_PROVIDER) return;
    if (!isRecord(event.payload)) return;

    return {
      ...event.payload,
      temperature: DEV_CORP_TEMPERATURE,
      top_p: DEV_CORP_TOP_P,
    };
  });
}

이 hook은 provider가 dev-corp일 때만 요청 payload에 temperature: 0.2, top_p: 0.95를 추가한다. dev-corp-direct, dev-corp-spark01 같은 direct provider에는 적용하지 않는다.

이미 실행 중인 Pi session에는 /reload 또는 재시작 후 반영한다.

권장 요청

기본 권장 호출은 stream:true다. think, reasoning_effort, thinking_token_budget은 보내지 않는다.

curl -N http://digitalplatform-iop.cloud:18086/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "model": "gemma4:26b",
    "messages": [
      {
        "role": "user",
        "content": "간단히 응답해줘."
      }
    ],
    "stream": true
  }'

Streaming을 처리하지 않는 client에서는 선택적으로 stream:false를 사용할 수 있다.

curl -fsS http://digitalplatform-iop.cloud:18086/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{"model":"gemma4:26b","messages":[{"role":"user","content":"ok만 응답해줘."}],"stream":false}'

파라미터

파라미터	권장
model	gemma4:26b
stream	기본 true, 필요하면 false
temperature	Pi dev-corp profile은 extension으로 0.2 고정
top_p	Pi dev-corp profile은 extension으로 0.95 고정
think	생략
reasoning_effort	생략
thinking_token_budget	생략
include_reasoning	숨김 보장용으로 쓰지 않음

Reasoning 표시 옵션

응답에 reasoning field가 포함될 수 있다. 표시하지 않는 UX가 필요하면 호출하는 client에서 아래 field를 렌더링 대상에서 제외하는 방식으로 처리할 수 있다.

• non-stream: choices[].message.reasoning_content, choices[].message.reasoning, choices[].message.reasoning_text
• stream: choices[].delta.reasoning_content, choices[].delta.reasoning, choices[].delta.reasoning_text

include_reasoning=false만으로 reasoning 표시 여부가 항상 제어된다고 가정하지 않는다.