From ef236878ffbbe93ac94235e515fb2f349b4e3590 Mon Sep 17 00:00:00 2001 From: leedongmyun Date: Thu, 9 Jul 2026 21:02:50 +0900 Subject: [PATCH] docs: update dev-corp openai-compatible call and pi settings guide --- docs/dev-corp-openai-compatible-call-guide.md | 134 +++--------- docs/dev-corp-pi-settings-guide.md | 197 ++++++++---------- 2 files changed, 110 insertions(+), 221 deletions(-) diff --git a/docs/dev-corp-openai-compatible-call-guide.md b/docs/dev-corp-openai-compatible-call-guide.md index 98c0781..c6d6c82 100644 --- a/docs/dev-corp-openai-compatible-call-guide.md +++ b/docs/dev-corp-openai-compatible-call-guide.md @@ -1,54 +1,22 @@ -# dev-corp OpenAI-Compatible Direct Call Guide +# dev-corp OpenAI-Compatible Call Guide -이 문서는 dev-corp public Edge를 OpenAI-compatible HTTP client에서 직접 호출할 때의 사람용 가이드다. 계약 원문은 `agent-contract/outer/openai-compatible-api.md`이며, 여기서는 `digitalplatform-iop.cloud` 외부 호출에 필요한 값과 dev-corp `gemma4:26b` provider-pool 한계만 정리한다. Pi coding agent 설정은 `docs/dev-corp-pi-settings-guide.md`를 따른다. +dev-corp `gemma4:26b` 모델을 OpenAI-compatible 방식으로 직접 호출할 때 필요한 최소 설정이다. -## 대상 범위 - -- 환경: dev-corp public Edge -- Base URL: `http://digitalplatform-iop.cloud:18086/v1` -- 기본 endpoint: `POST /v1/chat/completions` -- 모델 alias: `gemma4:26b` -- 인증: `Authorization: Bearer ` -- 기준 호출 방식: OpenAI-compatible Chat Completions 표준 HTTP 요청 - -`/v1/responses`는 dev-corp `gemma4:26b` provider-pool에서 raw passthrough parity 전까지 지원하지 않는다. 외부 표준 호출은 `/v1/chat/completions`를 기준으로 한다. - -## 기본 설정 +## 기본값 | 항목 | 값 | | --- | --- | | Base URL | `http://digitalplatform-iop.cloud:18086/v1` | -| Models endpoint | `GET /v1/models` | | Chat endpoint | `POST /v1/chat/completions` | +| Models endpoint | `GET /v1/models` | | Model | `gemma4:26b` | -| Content-Type | `application/json` | -| Authorization | `Bearer ` | -| Response mode | `metadata.iop_response_mode` 생략, 기본 `passthrough` | -| Streaming | client가 SSE를 처리할 수 있으면 `stream:true`, 아니면 `stream:false` | +| Auth header | `Authorization: Bearer ` | -토큰 원문은 tracked 문서, 예시 파일, 로그에 남기지 않는다. +`/v1/responses`가 아니라 `/v1/chat/completions`를 사용한다. ## 권장 요청 -가장 안정적인 기본 요청은 `think`, `reasoning_effort`, `thinking_token_budget`을 직접 지정하지 않는 형태다. 이렇게 호출하면 dev-corp `gemma4:26b` provider-pool의 현재 catalog/runtime 기본값을 유지한다. - -```bash -curl -fsS http://digitalplatform-iop.cloud:18086/v1/chat/completions \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer ' \ - -d '{ - "model": "gemma4:26b", - "messages": [ - { - "role": "user", - "content": "간단히 현재 호출이 정상인지 확인해줘." - } - ], - "stream": false - }' -``` - -Streaming이 필요한 client는 `stream:true`를 명시하고 SSE `data:` chunk를 처리한다. +기본 권장 호출은 `stream:true`다. `think`, `reasoning_effort`, `thinking_token_budget`은 보내지 않는다. ```bash curl -N http://digitalplatform-iop.cloud:18086/v1/chat/completions \ @@ -59,73 +27,14 @@ curl -N http://digitalplatform-iop.cloud:18086/v1/chat/completions \ "messages": [ { "role": "user", - "content": "한 문장으로 응답해줘." + "content": "간단히 응답해줘." } ], "stream": true }' ``` -## 파라미터 기준 - -| 파라미터 | 권장값 | 이유 | -| --- | --- | --- | -| `model` | `gemma4:26b` | dev-corp provider-pool의 외부 alias다. | -| `stream` | client 처리 방식에 맞게 `false` 또는 `true` | `false`는 JSON body, `true`는 SSE stream을 반환한다. | -| `think` | 생략 | 현재 Gemma4 runtime은 thinking enabled 기준으로 튜닝되어 있다. | -| `reasoning_effort` | 생략 | `none`은 thinking disable 의도라 기본 안정 호출에 맞지 않는다. | -| `thinking_token_budget` | 생략 | 생략하면 IOP catalog의 dev-corp `gemma4:26b` 기본 thinking budget을 사용한다. 명시하면 최적화된 기본값을 바꾸는 측정이 된다. | -| `include_reasoning` | hide 보장용으로 사용하지 않음 | provider-pool pure `passthrough`는 provider body 보존이 우선이라 IOP-side reasoning 제거를 보장하지 않는다. | -| `metadata.iop_response_mode` | 생략 또는 `passthrough` | provider-original 응답을 relay한다. | -| `metadata.iop_response_mode="passthrough+sideband"` | 관측이 필요할 때만 사용 | provider body에 IOP sideband가 추가되며 hide 동작은 아니다. | -| `metadata.iop_response_mode="transformed"` | 사용하지 않음 | provider model group route에서는 `400 invalid_request_error`로 거부된다. | - -Provider 전용 field인 `chat_template_kwargs`, `format`, `keep_alive`, `options`는 Chat Completions 외부 요청 body에 넣지 않는다. 이 값들은 dev-corp provider runtime 쪽 최적화 영역이며, OpenAI-compatible public Edge 호출자가 직접 조작하는 계약이 아니다. - -## Reasoning 처리 - -dev-corp `gemma4:26b` provider-pool은 pure `passthrough`를 기본으로 한다. 따라서 provider가 reasoning field를 반환하면 Edge는 그 field를 보존할 수 있다. - -Non-stream 응답에서 client가 숨길 수 있는 대표 field: - -- `choices[].message.reasoning_content` -- `choices[].message.reasoning` -- `choices[].message.reasoning_text` - -Streaming 응답에서 client가 숨길 수 있는 대표 delta field: - -- `choices[].delta.reasoning_content` -- `choices[].delta.reasoning` -- `choices[].delta.reasoning_text` - -사용자에게 reasoning을 보여주지 않아야 하는 client는 위 field를 표시/저장/후속 prompt에 주입하지 않도록 client 쪽에서 필터링한다. `include_reasoning=false`만으로 dev-corp `gemma4:26b` provider-pool에서 reasoning이 제거된다고 가정하지 않는다. - -## Gemma4 설정으로 인한 한계 - -dev-corp `gemma4:26b` provider-pool은 Gemma4 agent/tool-call 호환성을 위해 vLLM/vLLM-MLX runtime을 thinking enabled, Gemma4 parser/template, long-context 기준으로 맞춰 둔 상태다. 이 설정은 현재 동작 가능한 최적값에 가깝기 때문에 외부 caller가 요청 파라미터로 thinking 동작을 끄거나 budget을 바꾸면 backend별로 무시, 오류, 품질 저하, tool-call drift가 날 수 있다. - -현재 한계: - -- `think=false`는 “응답에서 reasoning만 숨김”이 아니라 thinking disable 요청이다. -- `reasoning_effort="none"`도 thinking disable 의도로 해석된다. -- 명시적 `thinking_token_budget`은 dev-corp 기본 budget을 바꾸는 요청이다. -- `include_reasoning=false`는 provider-pool pure `passthrough`에서 hide-only 스위치가 아니다. -- streaming 응답에는 reasoning delta가 먼저 오고 최종 content가 뒤따를 수 있다. -- provider-pool은 여러 runtime 후보를 사용하므로 token 단위 출력, reasoning field 이름, chunk 경계가 완전히 동일하다고 가정하지 않는다. -- exact-output match보다 HTTP 성공, 정상 JSON/SSE 구조, 최종 assistant content 존재 여부를 우선 판정한다. - -Reasoning을 provider에서 생성하게 두되 외부 사용자에게 보이지 않게 하려면, 현재 안정 기준은 `think` 관련 파라미터를 생략하고 client에서 reasoning field를 무시하는 것이다. - -## 검증 순서 - -1. Model 목록 확인: - -```bash -curl -fsS http://digitalplatform-iop.cloud:18086/v1/models \ - -H 'Authorization: Bearer ' -``` - -2. Non-stream Chat Completions 확인: +Streaming을 처리하지 않는 client에서는 선택적으로 `stream:false`를 사용할 수 있다. ```bash curl -fsS http://digitalplatform-iop.cloud:18086/v1/chat/completions \ @@ -134,13 +43,22 @@ curl -fsS http://digitalplatform-iop.cloud:18086/v1/chat/completions \ -d '{"model":"gemma4:26b","messages":[{"role":"user","content":"ok만 응답해줘."}],"stream":false}' ``` -3. Streaming Chat Completions 확인: +## 파라미터 -```bash -curl -N http://digitalplatform-iop.cloud:18086/v1/chat/completions \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer ' \ - -d '{"model":"gemma4:26b","messages":[{"role":"user","content":"ok만 응답해줘."}],"stream":true}' -``` +| 파라미터 | 권장 | +| --- | --- | +| `model` | `gemma4:26b` | +| `stream` | 기본 `true`, 필요하면 `false` | +| `think` | 생략 | +| `reasoning_effort` | 생략 | +| `thinking_token_budget` | 생략 | +| `include_reasoning` | 숨김 보장용으로 쓰지 않음 | -성공 판정은 HTTP 200, OpenAI-compatible `choices[]` 구조, 최종 assistant 응답 수신 기준으로 한다. Reasoning field가 포함되는 것만으로 실패로 보지 않는다. +## 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 표시 여부가 항상 제어된다고 가정하지 않는다. diff --git a/docs/dev-corp-pi-settings-guide.md b/docs/dev-corp-pi-settings-guide.md index 2a49327..f06d518 100644 --- a/docs/dev-corp-pi-settings-guide.md +++ b/docs/dev-corp-pi-settings-guide.md @@ -1,33 +1,36 @@ # dev-corp Pi Settings Guide -이 문서는 host-local Pi coding agent를 dev-corp `gemma4:26b` provider-pool에 맞춰 설정할 때의 기준이다. 일반 OpenAI-compatible HTTP 직접 호출은 `docs/dev-corp-openai-compatible-call-guide.md`를 따른다. +Pi를 dev-corp `gemma4:26b`로 사용하기 위한 최소 설치/설정 기준이다. -## 대상 범위 +## 설치 -- Pi package: `pi-coding-agent` -- 확인된 Pi version: `0.80.3` -- Pi binary: `pi` -- 설정 디렉터리: `~/.pi/agent` -- 설정 파일: - - `~/.pi/agent/settings.json` - - `~/.pi/agent/models.json` -- 대상 provider: `dev-corp` -- 대상 model: `gemma4:26b` -- Base URL: `http://digitalplatform-iop.cloud:18086/v1` +Pi `0.80.3`은 Node.js `22.19.0` 이상이 필요하다. -이 가이드는 dev-corp Gemma4 Pi profile 전용이다. dev/Qwen profile, direct provider 실험 profile, IOP Edge/Node/provider/vLLM runtime 설정으로 일반화하지 않는다. +```bash +node --version +npm --version +npm install -g @earendil-works/pi-coding-agent@0.80.3 +pi --version +``` -## 핵심 원칙 +`pi --version`이 `0.80.3`이면 정상이다. -- Pi 쪽 설정만 바꾼다. IOP Edge config, Node config, provider runtime, vLLM/vLLM-MLX launch option은 건드리지 않는다. -- `apiKey`, `authHeader` 같은 secret 값은 새로 출력하거나 tracked 문서에 기록하지 않는다. -- `dev-corp` provider가 기본값이어야 하며 direct provider profile을 기본값으로 두지 않는다. -- Pi의 `openai-completions` 경로는 Chat Completions streaming 호출 기준이다. 일반 HTTP `stream:false` 측정은 Pi가 아니라 표준 caller 가이드에서 다룬다. -- dev-corp `gemma4:26b`는 provider-pool catalog와 provider runtime이 thinking enabled 기준으로 맞춰져 있다. Pi에서 thinking disable을 시도하지 않는다. +## 설정 파일 -## settings.json 기준 +설정 위치: -`~/.pi/agent/settings.json`의 dev-corp 기준값: +```text +~/.pi/agent/settings.json +~/.pi/agent/models.json +``` + +디렉터리가 없으면 만든다. + +```bash +mkdir -p ~/.pi/agent +``` + +## settings.json ```json { @@ -44,18 +47,16 @@ } }, "enabledModels": [ - "dev-corp-direct/**", - "dev-corp-spark01/**", "dev-corp/*" ] } ``` -`lastChangelogVersion`, `theme` 같은 Pi UI/local preference field는 기존 값을 보존한다. +기존 `theme`, `lastChangelogVersion` 같은 개인 설정은 유지해도 된다. -## models.json 기준 +## models.json -`~/.pi/agent/models.json`에는 최소한 `providers.dev-corp`가 아래 의미를 가져야 한다. 예시의 ``은 새 값으로 덮어쓰지 말고 기존 값을 유지한다는 뜻이다. +`apiKey`에는 실제 토큰을 넣는다. 토큰은 문서, 로그, 공유 화면에 남기지 않는다. ```json { @@ -63,8 +64,8 @@ "dev-corp": { "baseUrl": "http://digitalplatform-iop.cloud:18086/v1", "api": "openai-completions", - "apiKey": "", - "authHeader": "", + "apiKey": "", + "authHeader": true, "compat": { "supportsStore": false, "supportsDeveloperRole": false, @@ -96,109 +97,79 @@ } ``` -`dev-corp-direct`와 `dev-corp-spark01` provider가 있더라도 fallback/실험용으로만 둔다. 기본 provider/model은 항상 `dev-corp` / `gemma4:26b`다. +## 주의 -## Gemma4 한계와 Pi 설정 의미 +- `supportsReasoningEffort`는 `false`로 둔다. +- `think=false`, `reasoning_effort=none`, `thinking_token_budget`을 강제로 추가하지 않는다. +- Pi는 `openai-completions` 기준으로 streaming 호출을 기본 사용한다. non-stream이 필요한 경우는 Pi가 아니라 일반 OpenAI-compatible 호출에서 `stream:false`로 선택한다. +- reasoning 표시 여부는 Pi UI나 client 표시 정책에서 선택적으로 처리한다. -현재 dev-corp `gemma4:26b` provider-pool은 Gemma4 agent/tool-call 호환성을 위해 provider runtime을 `reasoning_parser=gemma4`, `tool_call_parser=gemma4`, thinking enabled, long-context 기준으로 맞춰 둔 상태다. 이 값들은 provider 쪽 최적화 지점이므로 Pi 설정에서 우회하지 않는다. - -주의할 점: - -- `supportsReasoningEffort`는 `false`로 둔다. `true`로 바꾸면 Pi가 `reasoning_effort`를 보낼 수 있고, 현재 provider-pool 안정 경로와 어긋날 수 있다. -- `defaultThinkingLevel`은 `high`로 둔다. 단, dev-corp `supportsReasoningEffort=false` 기준에서는 Pi가 top-level `reasoning_effort=high`를 보내는 용도가 아니라 profile alignment와 UI 기준값이다. -- `hideThinkingBlock`은 현재 기준 `false`다. reasoning이 흘러오는지 관측 가능한 baseline을 유지한다. UI에서 숨김이 필요하더라도 provider thinking disable과 혼동하지 않는다. -- `thinking_token_budget`, `think=false`, `reasoning_effort=none` 같은 요청 파라미터를 Pi 설정으로 강제하지 않는다. -- Pi가 보는 context window는 `262144`, max output token 기준은 `32768`이다. provider runtime과 IOP catalog도 이 범위에 맞춰져 있어야 한다. - -Reasoning을 생성하게 두되 사용자에게 노출하지 않는 정책은 Pi UI/rendering 또는 별도 client filtering 문제다. provider/vLLM 설정이나 IOP provider-pool 기본 파라미터를 바꿔 해결하지 않는다. - -## 검증 - -설정 후 secret을 출력하지 않는 범위에서 아래를 확인한다. +## 확인 ```bash pi --version -jq '{defaultProvider, defaultModel, defaultThinkingLevel, hideThinkingBlock, httpIdleTimeoutMs, retry, enabledModels}' ~/.pi/agent/settings.json +jq '{defaultProvider, defaultModel, defaultThinkingLevel, hideThinkingBlock}' ~/.pi/agent/settings.json jq '.providers["dev-corp"] | { baseUrl, api, hasApiKey: has("apiKey"), - hasAuthHeader: has("authHeader"), + authHeader, compat, models }' ~/.pi/agent/models.json ``` -기대값: - -- `pi --version`은 현재 기준 `0.80.3` -- `defaultProvider`는 `dev-corp` -- `defaultModel`은 `gemma4:26b` -- `defaultThinkingLevel`은 `high` -- `providers.dev-corp.baseUrl`은 `http://digitalplatform-iop.cloud:18086/v1` -- `providers.dev-corp.api`는 `openai-completions` -- `providers.dev-corp.compat.supportsReasoningEffort`는 `false` -- `providers.dev-corp.compat.maxTokensField`는 `max_tokens` -- `providers.dev-corp.models[0].contextWindow`는 `262144` -- `providers.dev-corp.models[0].maxTokens`는 `32768` - -실제 호출 검증은 짧은 prompt로 수행한다. tool-call 검증이 목적이면 일반 chat smoke와 별도로 forced tool call, auto tool call, streaming `delta.tool_calls`, tool result 후 최종 답변을 확인한다. - ## Codex/Claude 작업 프롬프트 -아래 프롬프트는 Codex나 Claude에게 host-local Pi 설정을 맡길 때 그대로 전달하는 기준이다. - ```text -현재 호스트의 Pi coding agent를 dev-corp Gemma4 provider-pool 기준으로 맞춰줘. +현재 호스트의 Pi를 dev-corp gemma4:26b 기준으로 설치/설정해줘. -범위: -- 수정 가능: ~/.pi/agent/settings.json, ~/.pi/agent/models.json -- 수정 금지: IOP repo 설정, Edge config, Node config, provider runtime, vLLM/vLLM-MLX start script, secret 원문 출력 -- 현재 기준 provider/model: dev-corp / gemma4:26b -- Base URL: http://digitalplatform-iop.cloud:18086/v1 -- Pi API: openai-completions +수정 가능: +- Pi 설치 +- ~/.pi/agent/settings.json +- ~/.pi/agent/models.json -작업 규칙: -1. 먼저 pi --version, ~/.pi/agent/settings.json, ~/.pi/agent/models.json 구조를 확인해. -2. apiKey, authHeader, token, secret 값은 화면에 출력하지 말고 기존 값을 보존해. -3. 편집 전 settings.json과 models.json을 timestamp가 붙은 백업 파일로 복사해. -4. settings.json에는 아래 기준을 반영해: - - defaultProvider: dev-corp - - defaultModel: gemma4:26b - - defaultThinkingLevel: high - - hideThinkingBlock: false - - httpIdleTimeoutMs: 300000 - - retry.provider.timeoutMs: 300000 - - retry.provider.maxRetries: 0 - - retry.provider.maxRetryDelayMs: 60000 - - enabledModels: ["dev-corp-direct/**", "dev-corp-spark01/**", "dev-corp/*"] - - theme, lastChangelogVersion 등 기존 UI/local preference는 보존 -5. models.json의 providers.dev-corp는 아래 기준을 반영해: - - baseUrl: http://digitalplatform-iop.cloud:18086/v1 - - api: openai-completions - - 기존 apiKey/authHeader는 보존 - - compat.supportsStore: false - - compat.supportsDeveloperRole: false - - compat.supportsReasoningEffort: false - - compat.supportsUsageInStreaming: false - - compat.maxTokensField: max_tokens - - compat.requiresToolResultName: true - - compat.requiresAssistantAfterToolResult: true - - compat.supportsStrictMode: false - - model id: gemma4:26b - - model name: dev-corp gemma4:26b - - reasoning: true - - input: ["text"] - - contextWindow: 262144 - - maxTokens: 32768 - - cost input/output/cacheRead/cacheWrite: 0 -6. dev-corp-direct 또는 dev-corp-spark01 provider가 있으면 삭제하지 말고 fallback/실험용으로 보존해. 단 defaultProvider/defaultModel은 dev-corp/gemma4:26b로 둬. -7. supportsReasoningEffort를 true로 바꾸거나 think=false, reasoning_effort=none, thinking_token_budget 강제 설정을 추가하지 마. dev-corp Gemma4 provider-pool은 현재 thinking enabled 기준으로 튜닝되어 있고, reasoning hide는 provider 설정 변경이 아니라 client/UI 처리 문제야. -8. 변경 후 jq로 secret 없이 핵심 값만 출력해서 검증해. +수정 금지: +- 이 저장소 코드와 설정 +- 서버/모델 실행 설정 +- 토큰 원문 출력 -검증 출력에는 apiKey/authHeader 원문을 절대 포함하지 말고, hasApiKey/hasAuthHeader boolean 정도만 보여줘. +설치: +- Node.js >=22.19.0 확인 +- npm install -g @earendil-works/pi-coding-agent@0.80.3 +- pi --version이 0.80.3인지 확인 + +settings.json: +- defaultProvider: dev-corp +- defaultModel: gemma4:26b +- defaultThinkingLevel: high +- hideThinkingBlock: false +- httpIdleTimeoutMs: 300000 +- retry.provider.timeoutMs: 300000 +- retry.provider.maxRetries: 0 +- retry.provider.maxRetryDelayMs: 60000 +- enabledModels: ["dev-corp/*"] + +models.json: +- providers.dev-corp.baseUrl: http://digitalplatform-iop.cloud:18086/v1 +- providers.dev-corp.api: openai-completions +- providers.dev-corp.apiKey: 기존 값이 있으면 보존하고, 없으면 사용자에게 토큰을 요청 +- providers.dev-corp.authHeader: true +- compat.supportsStore: false +- compat.supportsDeveloperRole: false +- compat.supportsReasoningEffort: false +- compat.supportsUsageInStreaming: false +- compat.maxTokensField: max_tokens +- compat.requiresToolResultName: true +- compat.requiresAssistantAfterToolResult: true +- compat.supportsStrictMode: false +- model id: gemma4:26b +- model name: dev-corp gemma4:26b +- reasoning: true +- input: ["text"] +- contextWindow: 262144 +- maxTokens: 32768 + +think=false, reasoning_effort=none, thinking_token_budget 설정은 추가하지 마. +검증 출력에는 apiKey 원문을 포함하지 말고 hasApiKey boolean만 보여줘. ``` - -## 실패 시 되돌리기 - -백업한 파일로 `settings.json`과 `models.json`을 되돌린 뒤 Pi를 다시 실행한다. 실패가 `think=false`, `reasoning_effort`, `thinking_token_budget`, direct provider URL 변경과 관련되어 보이면 해당 변경을 제거하고 dev-corp public Edge route 기준으로 복원한다.