Skip to content

Commit

Permalink
Refactor: Revised Compute Network SDK Documentation: (#81)
Browse files Browse the repository at this point in the history 
* Updated the example in section 5.3 on request generation to enhance clarity,
  emphasizing that users' applications using the OpenAI SDK can seamlessly switch to our network.

* Added line breaks to prevent code blocks from being obscured, avoiding the need to scroll horizontally.

* Added detailed descriptions and explanations for input parameters like 'providerAddress'.

* Fixed the links in overview.md that navigate to sdk.md and marketplace.md.
  • Loading branch information
@Ravenyjh
Ravenyjh authored Dec 4, 2024
1 parent 6e972db commit 89fd48a
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 44 deletions.
4 changes: 2 additions & 2 deletions docs/build-with-0g/compute-network/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,6 @@ This brief overview introduces the foundational workflow. For more detailed step

If you're interested in becoming a **Service Provider**, please refer to [the Provider section](./provider.md) for detailed guidelines and requirements.

If you wish to leverage provider services to develop your own projects, relevant resources are available in [the Developer SDK section](./developer-sdk).
If you wish to leverage provider services to develop your own projects, relevant resources are available in [the Developer SDK section](./sdk).

For those looking to use the 0G Compute Network to access AI services, more information can be found in [the Marketplace section](./marketplace.md).
For those looking to use the 0G Compute Network to access AI services, more information can be found in [the Marketplace section](../marketplace.md).
117 changes: 75 additions & 42 deletions docs/build-with-0g/compute-network/sdk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,9 @@ import { createZGServingNetworkBroker } from "@0glabs/0g-serving-broker";
/**
* 'createZGServingNetworkBroker' is used to initialize ZGServingUserBroker
*
* @param {JsonRpcSigner | Wallet} signer - A signer that implements the 'JsonRpcSigner' or 'Wallet' interface from the ethers package.
* @param {JsonRpcSigner | Wallet} signer - A signer that implements the 'JsonRpcSigner' or
* 'Wallet' interface from the ethers package.
*
* @param {string} contractAddress - 0G Serving contract address, use default address if not provided.
*
* @returns broker instance.
Expand All @@ -48,11 +50,11 @@ const broker = await createZGServingNetworkBroker(signer);
/**
* 'listService' retrieves a list of services from the contract.
*
* @returns {Promise<ServiceStructOutput[]>} A promise that resolves to an array of ServiceStructOutput objects.
* @throws An error if the service list cannot be retrieved.
* @returns {Promise<ServiceStructOutput[]>} A promise that resolves to an array of ServiceStructOutput
* objects.
*
* type ServiceStructOutput = {
* provider: string; // Address of the provider
* provider: string; // Provider's wallet address, which is the unique identifier for the provider.
* name: string;
* serviceType: string;
* url: string;
Expand All @@ -61,6 +63,8 @@ const broker = await createZGServingNetworkBroker(signer);
* updatedAt: bigint;
* model: string;
* };
*
* @throws An error if the service list cannot be retrieved.
*/
const services = await broker.listService();
```
Expand All @@ -75,7 +79,9 @@ Before using the provider's services, you need to create an account specifically
/**
* 'addAccount' creates a new account in the contract.
*
* @param {string} providerAddress - The address of the provider for whom the account is being created.
* @param {string} providerAddress - The wallet address of the provider for whom the account is being created.
* You can obtain the `providerAddress` from the service list.
*
* @param {number} balance - The initial balance to be assigned to the new account. The unit is A0GI.
*
* @throws An error if the account creation fails.
Expand All @@ -89,7 +95,9 @@ await broker.addAccount(providerAddress, balance);
/**
* 'depositFund' deposits a specified amount of funds into an existing account.
*
* @param {string} account - The account identifier where the funds will be deposited.
* @param {string} providerAddress - The wallet address of the provider, which serves as the identifier
* for the account associated with the provider.
*
* @param {number} amount - The amount of funds to be deposited. The unit is A0GI.
*
* @throws An error if the deposit fails.
Expand All @@ -103,12 +111,15 @@ await broker.depositFund(providerAddress, amount);

```typescript
/**
* 'getServiceMetadata' returns metadata for the provider service.
* Includes:
* 1. Service endpoint of the provider service
* 2. Model information for the provider service
* 'getServiceMetadata' returns metadata for the provider service. Includes:
*
* 1. Service endpoint of the provider service
*
* 2. Model information for the provider service
*
* @param {string} providerAddress - The wallet address of the provider, which, along with the `serviceName`,
* serves as the identifier for the service in the 0G Compute Network.
*
* @param {string} providerAddress - The address of the provider.
* @param {string} serviceName - The name of the service.
*
* @returns { endpoint, model } - Object containing endpoint and model.
Expand All @@ -132,9 +143,13 @@ const { endpoint, model } = await broker.getServiceMetadata(
* is considered a settlement proof and will be used by the provider
* for settlement in contract.
*
* @param {string} providerAddress - The address of the provider.
* @param {string} providerAddress - The wallet address of the provider, which, along with the `serviceName`,
* serves as the identifier for the service in the 0G Compute Network.
*
* @param {string} serviceName - The name of the service.
* @param {string} content - The content being billed. For example, in a chatbot service, it is the text input by the user.
*
* @param {string} content - The content being billed. For example, in a chatbot service, it is the text input
* by the user.
*
* @returns headers. Records information such as the request fee and user signature.
*
Expand All @@ -149,22 +164,46 @@ const headers = await broker.getRequestHeaders(

#### 5.3 Send Request

After obtaining the `endpoint`, `model`, and `headers`, you can use client SDKs
compatible with the OpenAI interface to make requests.

**Note**: After receiving the response, you must use `processResponse` as demonstrated in step 5.4 to settle the response fee. Failure to do so will result in subsequent requests being denied due to unpaid fees. If this happens, you can manually settle the fee using `settleFee` as shown in step 5.5. The amount owed will be specified in the error message.

**Note**: Generated `headers` are valid for a single use only and cannot be reused.
Once you have the `endpoint`, `model`, and `headers`, you can send an HTTP request to the provider service, as demonstrated in the example below.

```typescript
/**
* Any SDK request methods that follow the OpenAI interface specifications can also be used.
* 1. The `endpoint` and `model` are obtained from `getServiceMetadata`.
* You only need to call `getServiceMetadata` once for each service.
*
* 2. The `headers` are obtained from `getRequestHeaders`.
* You need to generate `headers` for each request, as they depend on the request content.
*
* 3. The `content` is the input data for the request and should match the input used in `getRequestHeaders`.
*
* Here is an example using the OpenAI TS SDK.
* 4. The organization of the message content may vary depending on the provider service.
* Currently, the 0G Compute Network supports OpenAI's format.
*/
await fetch(`${endpoint}/chat/completions`, {
method: "POST",
headers: {
"Content-Type": "application/json",
...headers,
},
body: JSON.stringify({
messages: [{ role: "system", content }],
model: model,
}),
});

/**
* Already using the OpenAI SDK in your application? Seamlessly decentralize your application by switching
* to the 0G Compute Network. Here's how to modify your OpenAI API call to use a 0G Compute Network service:
*
* 1. Replace the OpenAI API endpoint and model with those obtained from `getServiceMetadata`.
*
* 2. Leave the API key field empty.
*
* 3. Add the billing headers generated by `getRequestHeaders`.
*/
const openai = new OpenAI({
baseURL: endpoint,
apiKey: "",
apiKey: " ",
});
const completion = await openai.chat.completions.create(
{
Expand All @@ -177,23 +216,12 @@ const completion = await openai.chat.completions.create(
},
}
);

/**
* Alternatively, you can also use `fetch` to make the request.
*/
await fetch(`${endpoint}/chat/completions`, {
method: "POST",
headers: {
"Content-Type": "application/json",
...headers,
},
body: JSON.stringify({
messages: [{ role: "system", content }],
model: model,
}),
});
```

**Note**: After receiving the response, you must use `processResponse` as demonstrated in step 5.4 to settle the response fee. Failure to do so will result in subsequent requests being denied due to unpaid fees. If this happens, you can manually settle the fee using `settleFee` as shown in step 5.5. The amount owed will be specified in the error message.

**Note**: Generated `headers` are valid for a single use only and cannot be reused.

#### 5.4 Process Responses

```typescript
Expand All @@ -206,12 +234,15 @@ await fetch(`${endpoint}/chat/completions`, {
* with the chat ID.
*
* @param {string} providerAddress - The address of the provider.
*
* @param {string} serviceName - The name of the service.
* @param {string} content - The main content returned by the service. For example, in the case of a chatbot service,
* it would be the response text.
* @param {string} chatID - Only for verifiable services. You can provide the chat ID obtained from the response to
* automatically download the response signature. The function will verify the reliability of the response
* using the service's signing address.
*
* @param {string} content - The main content returned by the service. For example, in the case of a
* chatbot service, it would be the response text.
*
* @param {string} chatID - Only for verifiable services. You can provide the chat ID obtained from the
* response to automatically download the response signature. The function will verify the reliability
* of the response using the service's signing address.
*
* @returns A boolean value. True indicates the returned content is valid, otherwise it is invalid.
*
Expand All @@ -236,7 +267,9 @@ const valid = await broker.processResponse(
* you can manually call settleFee to settle the fee.
*
* @param {string} providerAddress - The address of the provider.
*
* @param {string} serviceName - The name of the service.
*
* @param {number} fee - The fee to be settled. The unit is A0GI.
*
* @returns A promise that resolves when the fee settlement is successful.
Expand Down

0 comments on commit 89fd48a

Please sign in to comment.