392 lines
8.1 KiB
Markdown
392 lines
8.1 KiB
Markdown
# ChatClient
|
|
|
|
The `ChatClient` provides methods for chat completions and conversation management.
|
|
|
|
## Initialization
|
|
|
|
```python
|
|
from fastgpt_client import ChatClient
|
|
|
|
client = ChatClient(
|
|
api_key="fastgpt-xxxxx",
|
|
base_url="http://localhost:3000"
|
|
)
|
|
```
|
|
|
|
## Methods
|
|
|
|
### create_chat_completion
|
|
|
|
Create a chat completion (synchronous or streaming).
|
|
|
|
```python
|
|
client.create_chat_completion(
|
|
messages: list[dict],
|
|
stream: bool = False,
|
|
chatId: str | None = None,
|
|
detail: bool = False,
|
|
variables: dict[str, Any] | None = None,
|
|
responseChatItemId: str | None = None
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `messages` | `list[dict]` | Yes | Array of message objects with `role` and `content` |
|
|
| `stream` | `bool` | No | Whether to stream the response (default: `False`) |
|
|
| `chatId` | `str` | No | Chat ID for conversation context |
|
|
| `detail` | `bool` | No | Whether to return detailed execution data (default: `False`) |
|
|
| `variables` | `dict` | No | Template variables for substitution |
|
|
| `responseChatItemId` | `str` | No | Custom ID for the response message |
|
|
|
|
**Example:**
|
|
|
|
```python
|
|
response = client.create_chat_completion(
|
|
messages=[
|
|
{"role": "user", "content": "Hello!"},
|
|
{"role": "assistant", "content": "Hi there!"},
|
|
{"role": "user", "content": "How are you?"}
|
|
],
|
|
stream=False
|
|
)
|
|
result = response.json()
|
|
print(result['choices'][0]['message']['content'])
|
|
```
|
|
|
|
---
|
|
|
|
### upload_chat_image
|
|
|
|
Upload an image to FastGPT's chat file storage and return a normalized file reference.
|
|
|
|
```python
|
|
image = client.upload_chat_image(
|
|
appId="app-123",
|
|
chatId="chat-123",
|
|
file_path="example.png"
|
|
)
|
|
|
|
response = client.create_chat_completion(
|
|
chatId="chat-123",
|
|
messages=[
|
|
{
|
|
"role": "user",
|
|
"content": [
|
|
{"type": "text", "text": "Describe this image"},
|
|
{"type": "image_url", "image_url": {"url": image["url"]}},
|
|
],
|
|
}
|
|
],
|
|
)
|
|
```
|
|
|
|
Returned file reference:
|
|
|
|
```python
|
|
{
|
|
"type": "img",
|
|
"name": "example.png",
|
|
"key": "chat/...",
|
|
"url": "https://...",
|
|
"previewUrl": "https://..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### upload_chat_file
|
|
|
|
Upload a generic chat file. This is the lower-level helper used by `upload_chat_image`.
|
|
|
|
```python
|
|
file_ref = client.upload_chat_file(
|
|
appId="app-123",
|
|
chatId="chat-123",
|
|
file_path="document.pdf",
|
|
file_type="doc"
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### presign_chat_file_post_url
|
|
|
|
Request a presigned upload URL for a chat file. The SDK supports both FastGPT response shapes:
|
|
|
|
- Presigned POST: `{ "url": "...", "fields": {...}, "maxSize": ... }`
|
|
- Presigned PUT: `{ "url": "...", "headers": {...}, "key": "...", "previewUrl": "..." }`
|
|
|
|
---
|
|
|
|
### presign_chat_file_get_url
|
|
|
|
Request a temporary preview/download URL by file `key`.
|
|
|
|
```python
|
|
preview_url = client.presign_chat_file_get_url(
|
|
appId="app-123",
|
|
key="chat/..."
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### get_chat_histories
|
|
|
|
Get chat histories for an application.
|
|
|
|
```python
|
|
client.get_chat_histories(
|
|
appId: str,
|
|
offset: int = 0,
|
|
pageSize: int = 20,
|
|
source: Literal["api", "online", "share", "test"] = "api"
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `offset` | `int` | No | Offset for pagination (default: `0`) |
|
|
| `pageSize` | `int` | No | Number of records per page (default: `20`) |
|
|
| `source` | `str` | No | Source filter (default: `"api"`) |
|
|
|
|
**Example:**
|
|
|
|
```python
|
|
response = client.get_chat_histories(
|
|
appId="app-123",
|
|
offset=0,
|
|
pageSize=20,
|
|
source="api"
|
|
)
|
|
data = response.json()
|
|
for chat in data['data']['list']:
|
|
print(f"{chat['title']}: {chat['chatId']}")
|
|
```
|
|
|
|
---
|
|
|
|
### get_chat_init
|
|
|
|
Get chat initialization information.
|
|
|
|
```python
|
|
client.get_chat_init(
|
|
appId: str,
|
|
chatId: str
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `chatId` | `str` | Yes | Chat ID |
|
|
|
|
---
|
|
|
|
### get_chat_records
|
|
|
|
Get chat records for a specific chat.
|
|
|
|
```python
|
|
client.get_chat_records(
|
|
appId: str,
|
|
chatId: str,
|
|
offset: int = 0,
|
|
pageSize: int = 10,
|
|
loadCustomFeedbacks: bool = False
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `chatId` | `str` | Yes | Chat ID |
|
|
| `offset` | `int` | No | Offset for pagination (default: `0`) |
|
|
| `pageSize` | `int` | No | Number of records per page (default: `10`) |
|
|
| `loadCustomFeedbacks` | `bool` | No | Whether to load custom feedbacks (default: `False`) |
|
|
|
|
---
|
|
|
|
### get_record_detail
|
|
|
|
Get detailed execution data for a specific record.
|
|
|
|
```python
|
|
client.get_record_detail(
|
|
appId: str,
|
|
chatId: str,
|
|
dataId: str
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `chatId` | `str` | Yes | Chat ID |
|
|
| `dataId` | `str` | Yes | Record ID |
|
|
|
|
---
|
|
|
|
### update_chat_history
|
|
|
|
Update chat history (title or pin status).
|
|
|
|
```python
|
|
client.update_chat_history(
|
|
appId: str,
|
|
chatId: str,
|
|
customTitle: str | None = None,
|
|
top: bool | None = None
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `chatId` | `str` | Yes | Chat ID |
|
|
| `customTitle` | `str` | No | Custom title for the chat |
|
|
| `top` | `bool` | No | Whether to pin the chat |
|
|
|
|
---
|
|
|
|
### delete_chat_history
|
|
|
|
Delete a chat history.
|
|
|
|
```python
|
|
client.delete_chat_history(
|
|
appId: str,
|
|
chatId: str
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `chatId` | `str` | Yes | Chat ID |
|
|
|
|
---
|
|
|
|
### clear_chat_histories
|
|
|
|
Clear all chat histories for an application.
|
|
|
|
```python
|
|
client.clear_chat_histories(
|
|
appId: str
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
|
|
---
|
|
|
|
### delete_chat_record
|
|
|
|
Delete a single chat record.
|
|
|
|
```python
|
|
client.delete_chat_record(
|
|
appId: str,
|
|
chatId: str,
|
|
contentId: str
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `chatId` | `str` | Yes | Chat ID |
|
|
| `contentId` | `str` | Yes | Content ID of the record |
|
|
|
|
---
|
|
|
|
### send_feedback
|
|
|
|
Send feedback for a chat message (like/dislike).
|
|
|
|
```python
|
|
client.send_feedback(
|
|
appId: str,
|
|
chatId: str,
|
|
dataId: str,
|
|
userGoodFeedback: str | None = None,
|
|
userBadFeedback: str | None = None
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `chatId` | `str` | Yes | Chat ID |
|
|
| `dataId` | `str` | Yes | Message ID |
|
|
| `userGoodFeedback` | `str` | No | Positive feedback text |
|
|
| `userBadFeedback` | `str` | No | Negative feedback text |
|
|
|
|
**Example:**
|
|
|
|
```python
|
|
# Like a message
|
|
client.send_feedback(
|
|
appId="app-123",
|
|
chatId="chat-123",
|
|
dataId="msg-123",
|
|
userGoodFeedback="Great answer!"
|
|
)
|
|
|
|
# Dislike a message
|
|
client.send_feedback(
|
|
appId="app-123",
|
|
chatId="chat-123",
|
|
dataId="msg-123",
|
|
userBadFeedback="Not helpful"
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### get_suggested_questions
|
|
|
|
Get suggested questions based on chat context.
|
|
|
|
```python
|
|
client.get_suggested_questions(
|
|
appId: str,
|
|
chatId: str,
|
|
questionGuide: dict[str, Any] | None = None
|
|
) -> httpx.Response
|
|
```
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `appId` | `str` | Yes | Application ID |
|
|
| `chatId` | `str` | Yes | Chat ID |
|
|
| `questionGuide` | `dict` | No | Custom configuration for question guide |
|